Think of modules like logically separated parts of the system. Each module can have its own
scripts. Controllers in modules are named the same way
as application/controllers, without namespace. And yes, you can potentially have
the same class name across your project and it is possible because module has priority over the rest of the application
and it "overrides" the "namespace" from the app.
It means that include path for module's controllers and module's library comes before the include path of the rest of
vendor has the lowest priority.
When framework is "running" controller from application/controllers, you're not able to access any module unless module is registered. The same is when framework is "running" controller class from module, you can't access other module's controllers nor library unless you use:
Long story short:
- if you're in the module, you see yourself and the main application
- if you're in the main application, you don't see any module unless module is registered
- if you're in the module, you don't see other modules unless other module is registered
In some rare cases, when registering module, you might want to initialise some stuff, like loading some custom and
totally different configuration needed just for this module to work. In this case, you can place
init.php in module's
modules/admin/init.php. You can place any code in here and it'll be executed every time module
Real World Example
Let's say you have a public website with a lot of sub pages, like contact page, product list, product details, search,
comments, small user area and etc. And now, you want to add to your site administration area and you want to provide
basic API for your users. That would be two modules:
Yes, you can simply create
AdminController in application/controllers where you
can handle all HTTP endpoints but then your
AdminController will probably have few or several thousand of lines of
code and that's not something we (developers) like. What if some other guy has to continue maintaining your code and
that guy is psychopath who knows where you live? Nobody wants that. This framework allows you not to have class files
with thousands of code.
Everything for public web can be placed in application/controllers and all models
and other logic can be placed in application/library because this is majority of the
site. To create a module, simple create subdirectory in
api so the structure looks like this:
modules | admin | | controllers | | library | | scripts | | views | api | | controllers | | library | | scripts | | views
Administration area usually have its own look, some special tables in database, like administrator sign in credentials and similar, but when you're signed in, you want to manage stuff from the public web site.
When using DefaultRoute, module named
admin will "take" the URI namespace, so every request
that goes to
http://your-domain.com/admin will end up in your
admin module. If
admin module doesn't exist,
framework will look up for
AdminController class in application/controllers.
That's the "namespace overriding" mentioned on the top of this page.
When mapping database tables from public web site into models, we're recommending that you place those files under
namespace in application/library.
When mapping module specific database tables, we're recommending that you place those files under module's
modules | admin | | controllers | | library | | | Db | | | | AdminUser.php - namespace Db, class AdminUser | | scripts | | views
And now, if you try to use
\Db\AdminUser in your
admin in controllers, framework will first look it up on
modules/admin/library. If class is not there, it'll then continue to look it up
If you're in application/controllers and you try to use
get exception telling you class can't be found. If you really have to access this class from
application's controllers, then register your module before using
This is not recommended because it signalizes that you might have an architectural problem in your project.
Place module specific CLI scripts in this directory. For example, if you have script
modules/admin/scripts/backup.php, you can run it with:
./koldy run admin:backup
You can find more info on Running CLI scripts in modules.
We mentioned that administration area usually have its own look. That's why you have
views folder. Place your admin
specific view templates in this directory. If you created template file on
modules/admin/views/base.phtml, then you
can simply use it like:
Unlike library, module's views are accessible from application or any other module because when creating view, you have to prefix it with the module name. You have to prefix it even if you're in the module's controller.