Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sebastiaanluca/laravel-module-loader
THIS PACKAGE HAS BEEN DEPRECATED — A lightweight package to organize your code into contextual modules.
https://github.com/sebastiaanluca/laravel-module-loader
domain laravel module modules
Last synced: 3 months ago
JSON representation
THIS PACKAGE HAS BEEN DEPRECATED — A lightweight package to organize your code into contextual modules.
- Host: GitHub
- URL: https://github.com/sebastiaanluca/laravel-module-loader
- Owner: sebastiaanluca
- License: mit
- Archived: true
- Created: 2018-07-24T08:25:37.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-03-11T13:44:02.000Z (over 3 years ago)
- Last Synced: 2024-04-04T19:33:10.670Z (7 months ago)
- Topics: domain, laravel, module, modules
- Language: PHP
- Homepage: https://sebastiaanluca.com
- Size: 154 KB
- Stars: 77
- Watchers: 2
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# A lightweight package to split your code into contextual modules
**Laravel Module Loader helps you organize your project by splitting your domain code in contextual modules.**
By default, Laravel provides you with an `app/` directory to put all your classes in. In medium to large projects, you usually end up having a monolithic `app/` directory with tens or hundreds of directories and classes. To make *some* sense of that, they're typically organized per *type of class* (e.g. providers, services, models, …) too.
**An alternative** to that is organizing your code in groups that belong in the same context, i.e. modules. Since you usually develop one feature at a time, it makes it easier for you and other developers to find related code when working in that context.
Additionally, this lightweight module package provides some added benefits when making use of the include module service provider, including:
- individual configuration;
- publishable configuration;
- migrations;
- seeders;
- Eloquent factories;
- (PHP array or JSON) translations;
- views;
- Eloquent polymorphic mapping support;
- automatic event listener or subscriber registration;
- and automatic [router mapping](https://github.com/sebastiaanluca/laravel-router).
### Example
To give you a sense of how a modularized project is structured, take for instance a users, documents, and a shopping cart module:
```
User/
database/
factories/
migrations/
seeds/
resources/
lang/
views/
src/
Commands/
Jobs/
Models/
Providers/
UserServiceProvider
tests/
UserTestCase
Document/
resources/
lang/
src/
Models/
Providers/
DocumentServiceProvider
ShoppingCart/
src/
Providers/
ShoppingCartServiceProvider
```
## Table of contents
- [Requirements](#requirements)
- [How to install](#how-to-install)
- [Getting started](#getting-started)
- [Creating a module](#creating-a-module)
- [Caching in production environments](#caching-in-production-environments)
- [Going into detail](#going-into-detail)
- [Scanning and registering modules](#scanning-and-registering-modules)
- [Using a module service provider](#using-a-module-service-provider)
- [Individual module configuration](#individual-module-configuration)
- [Publishing a module's configuration](#publishing-a-modules-configuration)
- [Using migrations](#using-migrations)
- [Using factories](#using-factories)
- [Using seeders](#using-seeders)
- [Using translations](#using-translations)
- [Using views](#using-views)
- [Simplified polymorphic model type mapping](#simplified-polymorphic-model-type-mapping)
- [Simplified event listener registration](#simplified-event-listener-registration)
- [Automatic router mapping](#automatic-router-mapping)
- [Automatic service provider registration](#automatic-service-provider-registration)
- [Package configuration](#package-configuration)
- [Runtime autoloading](#runtime-autoloading)
- [Module directories](#module-directories)
- [Development environments](#development-environments)
- [License](#license)
- [Change log](#change-log)
- [Testing](#testing)
- [Contributing](#contributing)
- [Security](#security)
- [Credits](#credits)
- [About](#about)
## Requirements
- PHP 8 or higher
- Laravel 8 or higher
## How to install
Via Composer:
```bash
composer require sebastiaanluca/laravel-module-loader
```
## Getting started
There's only one required step to get started and that is to *create a module*.
### Creating a module
Say you want to create a module to group all your *user* related classes and files, run:
```
php artisan modules:create User
```
and the package will:
- scaffold your user module directories under your primary configured module directory;
- generate a correctly named (optional) service provider to fully enable the power of this package;
- and write its autoload information to your composer.json file.
Of course you can also do all of this manually. Create a `User` and `User/src` directory in any of your module directories and run `php artisan modules:refresh` afterwards to add it to your composer.json file (or do so manually too).
### Caching in production environments
*Optional*
To reduce the amount of files being read during application boot, you can opt to **cache a list of your module service providers** to improve load time. In addition to Composer providing a cached list of all your module classes, the package reads just the one cache file on boot and registers those instead of scanning all your module directories and loading them on-the-fly. Especially useful in production environments and advised to run during project deployment.
To cache all providers, run:
```
php artisan modules:cache
```
To clear the cache file, execute:
```
php artisan modules:clear
```
## Going into detail
### Scanning and registering modules
When you've manually created a new module, made some changes, added directories that need autoloading, and so on, you should refresh your modules:
```
php artisan modules:refresh
```
This will scan all your module directories for changes, write your modules' autoload configuration to composer.json (both classmap, PSR-4, and PSR-4 dev sections when applicable), and automatically update the Composer autoloader.
Your existing Composer configuration is not altered and no autoload entries are altered, unless:
- the module is missing;
- there are duplicate modules (by which one entry will be kept).
If you wish to keep all autoload entries for __modules that do not exist__, you can use the `--keep` option:
```
php artisan modules:refresh --keep
```
### Using a module service provider
*Optional*
A module should contain a service provider if you want your module to support:
- individual configuration;
- publishable configuration;
- migrations;
- seeders;
- Eloquent factories;
- (PHP array or JSON) translations;
- views;
- Eloquent polymorphic mapping support;
- automatic event listener or subscriber registration;
- and automatic [router mapping](https://github.com/sebastiaanluca/laravel-router).
When you create a module, a service provider is generated for you. If you want to create a provider yourself and have it automatically be registered on framework boot, create a class extending the correct base provider in your module's `src/Providers` directory.
Pay extra attention to the _studly cased_ naming of your provider, as it's only registered on boot if the class name starts with your module name.
```php
'value',
];
```
To retrieve a setting, call it like so:
```php
$setting = config('shopping-cart.setting')
// "value"
```
#### Publishing a module's configuration
*Optional; requires a [module service provider](#using-a-module-service-provider)*
If you don't want the configuration to reside in the module itself, you can either copy or move it to the root `/config` directory. Another option is to publish it like you would do for a package configuration file, i.e. let Laravel copy it for you:
```
php artisan vendor:publish
```
Then choose `* YourModule (configuration)` from the list.
Note that both configuration files will be merged ,but the one in the root `/config` directory will take precedence over the one in your module. If a same key is encountered in both files, the one from within your module will be ignored.
### Using migrations
*Optional; requires a [module service provider](#using-a-module-service-provider)*
Laravel Module Loader gives you 2 options when it comes to organizing migrations. Either you keep them in your default `/database/migrations` directory and maintain a chronological overview of all your migrations, or you store them contextually per module in e.g. `YourModule/database/migrations`.
Both locations are fine and interchangeable; i.e. you can combine both uses as they are sorted and executed by their date and time prefix.
### Using factories
*Optional; requires a [module service provider](#using-a-module-service-provider)*
Factories can be stored in your default `/database/factories` directory or per module in e.g. `YourModule/database/factories`. They are by default not namespaced and **only loaded in [development environments](#development-environments)** to prevent your application throwing errors when *autoload-dev* packages like Faker and so are are not installed on production systems.
### Using seeders
*Optional; requires a [module service provider](#using-a-module-service-provider)*
Seeders can be placed in your default `/database/seeds` directory or per module in `YourModule/database/seeds`. They are not namespaced and available globally, so watch out for identically named seeders across modules.
### Using translations
*Optional; requires a [module service provider](#using-a-module-service-provider)*
Translations are kept in the `/resources/lang` or `YourModule/resources/lang` module directory. If you use the latter and keep them within the module, remember to prefix your translation keys with the *snake cased* module name (as if you were using a package) to retrieve the correct value:
```php
@lang('your-module::dashboard.intro')
@lang('your-module::auth/password_reset.label')
```
### Using views
*Optional; requires a [module service provider](#using-a-module-service-provider)*
As with translations, views follow the same pattern. You can keep them in the default `/resources/views` directory or in `YourModule/resources/views`. To use a view or include a partial, prefix the path with your *snake cased* module name:
```php
view('my-module::dashboard')
@include('my-module::pages.auth.password_reset')
@include('my-module::pages/welcome')
```
### Simplified polymorphic model type mapping
*Optional; requires a [module service provider](#using-a-module-service-provider)*
Instead of manually calling `Relation::morphMap([])`, you can map the polymorphic types or aliases of your Eloquent models by defining a morph map array in your module service provider:
```php
Item::class,
'shopping_cart' => ShoppingCart::class,
];
}
```
Be sure to check out my other [auto morph map](https://github.com/sebastiaanluca/laravel-auto-morph-map) package to **automatically alias all your models** without writing any code.
### Simplified event listener registration
*Optional; requires a [module service provider](#using-a-module-service-provider)*
In the same way you can define a morph map in your module service provider, you can also define a list of event listeners or subscribers:
```php
[
UpdateUserInfo::class,
]
];
/**
* The subscriber classes to register.
*
* @var array
*/
protected $subscribe = [
UserEventSubscriber::class,
];
}
```
### Automatic router mapping
*Optional; requires a [module service provider](#using-a-module-service-provider)*
Handling and organizing routes in a medium or large Laravel application can get messy quite fast. To counter that ever-expanding list of routes, this package provides support for [sebastiaanluca/laravel-router](https://github.com/sebastiaanluca/laravel-router) to automatically register and map your contextual routes and routers:
```php