Package Override
You can customize a package in two areas: its MVC source and its language strings. Your changes stay in your project, so they are kept when you update the package in vendor/.
MVC Override
Copying the Source
The recommended method is to copy the package source with pkg:install, then change the route so it points to the copied class. Every request that uses the route then runs your copy:
// Your copy of the route file
use App\Module\Front\Article\ArticleListView;
$router->get('article_category', '/articles[/{path:.+}]')
->view(ArticleListView::class);Because the copy lives in your project, a package update does not overwrite your changes. The methods below are for smaller changes.
Adding a View Path
Use these methods when you replace a package's view model class but still want the package's layout templates. Add the package's views/ folder to the view path, so the templates are found without copying them.
namespace App\Module\Front\Article;
use Lyrasoft\Luna\Module\Front\Article\ArticleListView as BaseView;
class ArticleListView extends BaseView
{
// Your overrides of the view model here.
}Your view class calls addParentViewPath() to add the views/ folder of the package's view model:
use Windwalker\Core\View\View;
use Windwalker\Utilities\Iterator\PriorityQueue;
class ArticleListHtmlView extends View
{
public function prepare(): void
{
// Reads the views/ folder of the package's view model.
$this->addParentViewPath();
}
}Use addViewPath() when your view model does not extend a package class. Pass the class name or an object, and it reads the views/ folder beside that class file.
Both methods take an optional priority and namespace:
use Windwalker\Utilities\Iterator\PriorityQueue;
$this->addViewPath(
ArticleListView::class,
PriorityQueue::HIGH,
'main',
);Overriding Layouts
Use layoutPaths() to add folders that are searched for layout files before the defaults:
$this->layoutPaths(
__DIR__ . '/layouts/article',
);Each path is a folder that contains layout files.
Overriding Classes with DI Aliases
Add an aliases entry to etc/di.php to replace a class that the container creates. The alias maps the package class to your class:
// etc/di.php
return [
'aliases' => [
\Lyrasoft\Luna\Services\ArticleService::class
=> \App\Services\ArticleService::class,
],
];WARNING
Aliases apply only to objects that the container creates. Objects created with new still use the original class. Use $container->get(), app->retrieve(), or constructor injection to get the replacement.
Overriding Entities with class_alias
Use PHP's class_alias() to make the package class name resolve to your copy of the entity. Put the call in src/bootstrap.php:
// src/bootstrap.php
class_alias(
\App\Entity\Article::class,
\Lyrasoft\Luna\Entity\Article::class,
);INFO
Copy the entity into your project with pkg:install first, so that App\Entity\Article exists.
Language Override
Packages ship translation strings in resources/languages/, organized by locale. Copy a language file into your project and load it to override the package's text.
Loading Package Language Files
LangService reads a package's language files from its vendor/ folder. Load one file by name with loadFileFromVendor():
use Windwalker\Core\Language\LangService;
$lang = $container->get(LangService::class);
$lang->loadFileFromVendor('lyrasoft/luna', 'article', 'ini');The call above loads resources/languages/{locale}/article.ini from lyrasoft/luna. The fallback locale is loaded too.
To load every language file of a package, use loadAllFromVendor():
$lang->loadAllFromVendor('lyrasoft/luna', 'ini');Overriding Strings
Copy the language file into your project with pkg:install, or create it yourself. Then load it with loadFile():
$lang->loadFile('article', 'ini');Loading from a Custom Path
Use loadFileFromPath() or loadAllFromPath() when your language files are in a folder outside the default language paths:
$lang->loadFileFromPath(
'@root/resources/languages',
'article',
'ini',
'en-US',
);Next Steps
- Package Installation: copy the resources you want to override.