boboko/core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Feat: Moving things, updating OTP, cleaning stuff up

Browse Source
This commit is contained in:
Konstantinos Arvanitakis
2026-07-03 02:15:31 +03:00
parent 15bff15cad
commit ce08287641
23 changed files with 770 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/modules.md
+423
View File
@@ -0,0 +1,423 @@
# Module Architecture
This project uses standalone Composer packages for shared functionality, pulled into each e-shop app as regular dependencies. `boboko/core` (this repo) is the foundational module — every e-shop requires it. Other modules (e.g. `boboko/appointments`) require `boboko/core` in turn and layer additional, optional functionality on top.
Unlike an in-repo `modules/` directory, each module here lives in **its own repository** from day one. An app pulls it in via Composer, either from a `path` repository (local development, symlinked) or a `vcs`/Packagist reference (plain dev and production).
---
## Directory Structure
A module repository (e.g. `boboko-core`) is a self-contained Composer package:
```
boboko-core/ (this repo)
composer.json
config/
core.php
database/migrations/
resources/
views/
logos/
js/
docs/
src/
Auth/
Events/
Extensions/
Filament/Pages/
Mail/
Models/
Services/
Customer/
Extensions/
Listeners/
Models/
RelationManagers/
Command/
Providers/
CoreServiceProvider.php ← entry point, registers itself + config/migrations/assets
AuthServiceProvider.php ← staff/admin auth wiring not covered elsewhere
CustomerServiceProvider.php ← ModelManifest + Customer↔User event wiring
Stoic/
```
The e-shop app (`boboko-test`) consumes it as `vendor/boboko/core`:
```
boboko-test/
app/
Models/
Customer.php ← app-level model, extends Modules\Core\Customer\Models\Customer
User.php ← app-level model, dispatches Modules\Core\Auth\Events\UserCreated
Staff.php ← app-level model, extends Modules\Core\Auth\Models\Staff
Lunar/
Extensions/ ← app's own Filament resource extensions (source of truth, wired in PanelServiceProvider)
Pages/ ← app's own Create/Edit page overrides (event dispatch timing, prefill, etc.)
Providers/
AppServiceProvider.php
PanelServiceProvider.php ← all LunarPanel wiring for this app
EventServiceProvider.php ← all Event::listen registrations for this app
config/
core.php ← published from boboko-core, per-app overrides (e.g. auto_create_customer_for_user)
modules/
Appointments/ ← a second module, symlinked/required the same way as core
```
Within a module, organise by concern rather than by type (`Auth/`, `Customer/`, not `Models/`, `Services/` at the top level).
---
## Pulling In a Module
**In the app's root `composer.json`:**
```json
"require": {
"boboko/core": "^1.0"
},
"repositories": [
{
"type": "vcs",
"url": "https://code.radical-elements.com/boboko/core.git"
}
]
```
This is the **default** — a fresh `composer install` never depends on a local checkout existing.
**When developing the module itself alongside the app**, swap the `repositories` entry for a `path` repo pointing at a sibling checkout:
```json
"repositories": [
{
"type": "path",
"url": "../boboko-core",
"options": { "symlink": true }
}
]
```
This is a **manual, deliberate swap** of `composer.json` — not automated, since Composer has no clean built-in mechanism to merge an additional repository on top of the main list per-environment (`composer.local.json` is not auto-merged in Composer 2.x; `COMPOSER_REPOSITORIES` does not merge either — both were tested and ruled out). Swap it back to `vcs` before committing, so CI/prod builds never require `../boboko-core` to exist.
### Docker Compose: the local-core mount
`docker-compose.dev.yml` does **not** mount `../boboko-core` by default — normal app development never needs the sibling checkout present. A separate override file adds just that mount:
```
docker-compose.core-dev.yml ← adds ../boboko-core:/var/www/boboko-core to app/queue/scheduler
```
```bash
# normal app dev
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
# developing core locally (also requires the composer.json path-repo swap above)
docker compose -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.core-dev.yml up
# or: bin/dc-core.sh up
```
Docker Compose merges `volumes:` lists additively across `-f` files, so the override only needs to declare the one extra mount per service.
---
## Creating a New Module
**1. Create the repository and `composer.json`:**
```json
{
"name": "boboko/your-module",
"description": "What it does",
"type": "library",
"version": "1.0.0",
"require": {
"boboko/core": "^1.0"
},
"autoload": {
"psr-4": {
"Modules\\YourModule\\": "src/"
}
},
"extra": {
"laravel": {
"providers": [
"Modules\\YourModule\\Providers\\YourModuleServiceProvider"
]
}
}
}
```
**2. Create the service provider:**
```php
namespace Modules\YourModule\Providers;
use Illuminate\Support\ServiceProvider;
class YourModuleServiceProvider extends ServiceProvider
{
public function register(): void {}
public function boot(): void
{
$this->loadViewsFrom(__DIR__ . '/../../resources/views', 'your-module');
$this->loadMigrationsFrom(__DIR__ . '/../../database/migrations');
}
}
```
**Register every provider the module needs in `extra.laravel.providers`.** A module can define more than one provider (e.g. `CoreServiceProvider`, `AuthServiceProvider`, `CustomerServiceProvider`) — Composer's package auto-discovery only boots providers actually listed here. A provider class that exists but isn't listed silently never runs; this has bitten this project before (see "Provider Registration Pitfalls" below).
**3. Require it in the app's `composer.json`**, same as any other module (see "Pulling In a Module" above).
Then run `composer update boboko/your-module`.
---
## Provider Registration Pitfalls
Composer's Laravel package auto-discovery only boots providers explicitly listed in `extra.laravel.providers`. It is easy to write a second/third provider in a module (e.g. splitting concerns into `AuthServiceProvider`, `CustomerServiceProvider`) and forget to add it to that list — the class compiles fine, autoloads fine, and simply never boots. Symptoms are subtle: `ModelManifest::replace()` never runs, event listeners never attach, and nothing errors — code just silently does nothing.
**Before assuming a provider's `boot()` logic is live, check `vendor/composer/installed.json`'s `extra.laravel.providers` for the package**, not just `composer.json` (a local `path`-repo package's cached `extra` metadata does not refresh on file edits alone — `composer dump-autoload` is not enough; a full `composer update <package>` is required to re-read a changed `composer.json`, and lock-file version conflicts can block that update).
### Duplicate registration between module and app
When a module ships a provider that overlaps with app-level Filament wiring (e.g. both independently call `LunarPanel::extensions([...])` for the same resource, or both register the same model-created listener), only one should survive. Prefer whichever is **proven to run** in production (usually the app-level `PanelServiceProvider`/`CorePlugin` wiring, since that's what's actually referenced from the panel registration) and strip the duplicate from the module provider — don't leave both, since duplicate `created`/`updated` listeners fire twice (e.g. sending two invite emails).
---
## Extending the Staff Model via Traits
Modules never define their own `Staff` model. Instead, each module ships a trait with its behaviour, and `app/Models/Staff.php` opts in to whatever the app needs.
**1. Define a trait in your module:**
```php
namespace Modules\YourModule\Concerns;
trait HasYourFeature
{
public function yourRelationship(): HasMany
{
return $this->hasMany(YourModel::class);
}
}
```
**2. Use it in `app/Models/Staff.php`:**
```php
namespace App\Models;
use Modules\Core\Auth\Models\Staff as CoreStaff;
use Zap\Models\Concerns\HasSchedules;
use Modules\YourModule\Concerns\HasYourFeature;
class Staff extends CoreStaff
{
use HasSchedules;
use HasYourFeature;
}
```
The app decides which traits to compose — modules have no knowledge of each other.
---
## Model Inheritance Chain
```
Lunar\Admin\Models\Staff ← Lunar base (auth, roles, Filament)
└── Modules\Core\Auth\Models\Staff ← OTP fields
└── App\Models\Staff ← app model, composes all traits
Lunar\Models\Customer ← Lunar base (buyer, addresses, orders)
└── Modules\Core\Customer\Models\Customer ← full_name accessor, title suppressed
└── App\Models\Customer ← app model, emails()/phones(), Elorus fields
```
Modules never extend each other's `Staff`/`Customer`. If a module needs staff or customer behaviour, it ships a trait, or (for core-generic behaviour) it lives directly in the module's own model, which the app then extends.
**`Customer` is not Authenticatable.** Auth is handled entirely by `App\Models\User` (see "Customer/User Pairing" below) — this changed during this project; earlier revisions made `Customer` implement `Authenticatable` directly, which has since been reverted.
---
## Customer/User Pairing
Two independent Laravel models exist per person: `App\Models\User` (the only `Authenticatable` entity, `web` guard) and `App\Models\Customer` (Lunar's buyer record — addresses, orders, no login). They are linked via Lunar's own `customer_user` pivot table (`$customer->users()` / `$user->customers()` / `$user->latestCustomer()`), not a direct foreign key — this is Lunar's native relationship shape, not something this project invented.
**Which direction creates which depends on the app:**
- **Generic e-shop flow (core's default, `config('core.auto_create_customer_for_user')`, default `true`):** a storefront visitor supplies only an email (Shopify-style passwordless). `Modules\Core\Auth\Services\UserOtpService::generateAndSend()` finds-or-creates the `User`. A genuinely new `User` fires `Modules\Core\Auth\Events\UserCreated`, handled by `Modules\Core\Customer\Listeners\CreateCustomerForUser`, which creates a bare `Customer` (no name yet — nothing was collected at signup) and attaches it via the pivot.
- **This app's flow (`boboko-test`, flag set to `false` in its published `config/core.php`):** staff create a `Customer` directly (often pre-filled from an appointment booking) with real business data (name, email, VAT, etc.). `App\Events\CustomerCreated` (dispatched manually — see "Event Timing" below) is handled by `App\Listeners\CreateUserForCustomerListener`, which finds-or-creates the paired `User` by the customer's primary email.
**A shop opts out of core's default cascade by publishing and editing `config/core.php`:**
```bash
php artisan vendor:publish --tag=core-config
```
```php
// config/core.php
'auto_create_customer_for_user' => false,
```
Both listeners guard against the other direction re-triggering: they call `User::withoutEvents(...)` around `firstOrCreate`/save, so pairing a `Customer` never spuriously fires `UserCreated` (and vice versa) even if both directions are somehow active at once.
---
## Event Timing: Filament Repeaters and Model Events
**Do not dispatch domain events from a model's `$dispatchesEvents` (`created`/`updated`) when the event's listeners depend on related data saved via a Filament relationship `Repeater`** (e.g. `Repeater::make('emails')->relationship('emails')`). Filament's `CreateRecord`/`EditRecord` pages save the base record first (firing Eloquent's `created`/`updated` immediately), then save repeater-managed relations in a separate step afterward. A listener that reads `$customer->primaryEmail()` inside a `CustomerCreated`/`CustomerUpdated` handler triggered this way will silently see no email — no error, just a no-op.
**Fix:** dispatch the event manually from the Filament page's `afterCreate()`/`afterSave()` hook instead, once relations are guaranteed persisted:
```php
// app/Lunar/Pages/CreateCustomer.php
class CreateCustomer extends BaseCreateRecord
{
protected function afterCreate(): void
{
/** @var \App\Models\Customer $customer */
$customer = $this->record;
event(new CustomerCreated($customer));
}
}
```
```php
// app/Lunar/Pages/EditCustomer.php
class EditCustomer extends BaseEditCustomer // extends Lunar's own EditCustomer, not BaseEditRecord directly
{
public function afterSave(): void
{
parent::afterSave(); // preserves Lunar's own afterSave() behaviour (e.g. sync_with_search)
event(new CustomerUpdated($this->record));
}
}
```
Remove the corresponding entry from the model's `$dispatchesEvents` array so the event only fires once, from the page.
Both pages must be wired into the resource's `extendPages()`:
```php
public function extendPages(array $pages): array
{
$pages['create'] = CreateCustomer::route('/create');
$pages['edit'] = EditCustomer::route('/{record}/edit');
return $pages;
}
```
---
## Splitting Service Providers
When a service provider grows beyond a handful of responsibilities, split it into focused sub-providers and register **each one individually** in `extra.laravel.providers` (see "Provider Registration Pitfalls" above — registering only the entry-point provider silently drops the others).
**Each sub-provider owns one concern:**
```php
// AuthServiceProvider — staff auth wiring not already covered by the app's own CorePlugin/PanelServiceProvider
class AuthServiceProvider extends ServiceProvider
{
public function boot(): void
{
if ($this->app->runningInConsole()) {
$this->app->booted(fn () => $this->commands([CreateAdminCommand::class]));
}
}
}
// CustomerServiceProvider — customer model replacement + Customer/User event wiring
class CustomerServiceProvider extends ServiceProvider
{
public function boot(): void
{
ModelManifest::replace(LunarCustomer::class, Customer::class);
Event::listen(UserCreated::class, CreateCustomerForUser::class);
}
}
```
**Rule of thumb:** if a provider has more than one `use` group (e.g. Lunar imports alongside mail imports alongside event imports), it is doing too much. If two providers (module and app) would both register the same `LunarPanel::extensions()` call or the same model-event listener, one of them is redundant — see "Provider Registration Pitfalls."
---
## Filament Panel Integration
All `LunarPanel::*` calls that must run before `LunarPanel::register()` (which snapshots `getRelations()` and locks in Livewire component registrations) live in the app's `PanelServiceProvider::register()`:
```php
// PanelServiceProvider::register()
LunarPanel::extensions([...]); // must come before register()
LunarPanel::panel(fn ($panel) => ...);
LunarPanel::disableTwoFactorAuth();
LunarPanel::register(); // snapshots everything above
```
Module-level extensions belong in the module's own sub-provider **only if the app isn't already the one wiring that resource's extension** — check `PanelServiceProvider` first. The rule: if removing the module would break the configuration, it belongs in the module; if the app already owns that wiring (common for `CustomerResource`/`StaffResource` in this project), the module's own attempt to also wire it is dead weight or a duplicate-registration bug.
---
## Overriding Lunar Relation Managers
Lunar resources ship with their own relation managers (e.g. `CustomerResource` has `AddressRelationManager`, `UserRelationManager`). To replace or remove one:
**1. Create your relation manager extending the one you want to replace** (only if you need to keep it, with changes):
```php
// app/Lunar/RelationManagers/AddressRelationManager.php
class AddressRelationManager extends BaseAddressRelationManager
{
public function getDefaultTable(Table $table): Table { ... }
}
```
**2. In the resource extension's `getRelations()`, swap or filter it out:**
```php
class CustomerResourceExtension extends BaseExtension
{
public function getRelations(array $relations): array
{
$relations = array_map(
fn ($relation) => $relation == BaseAddressRelationManager::class
? AddressRelationManager::class
: $relation,
array_filter(
$relations,
fn ($relation) => $relation != BaseUserRelationManager::class, // drop entirely
)
);
return $relations;
}
}
```
**Always compare against the Lunar base class** (`Lunar\Admin\...\AddressRelationManager`), not an intermediate class from a module. If a module has already swapped it and your extension compares against the module's class, the swap silently fails when boot order changes.
**3. Register the extension in `PanelServiceProvider::register()` before `LunarPanel::register()`** — extensions registered later (e.g. in `boot()`) are too late; Livewire component names are already locked in.
---
## Layering Module and App Configuration
`LunarPanel::extensions()` **merges** — calling it twice for the same resource registers both extensions. They run in registration order, each receiving the result of the previous one. **Only do this deliberately** — if both a module's provider and the app's `PanelServiceProvider` register an extension for the same resource without intending to layer, you get duplicate behaviour (see "Provider Registration Pitfalls").
```php
// CustomerServiceProvider::boot() — Core's fields
LunarPanel::extensions([CustomerResource::class => CoreCustomerResourceExtension::class]);
// PanelServiceProvider::register() — App's fields, applied on top
LunarPanel::extensions([CustomerResource::class => AppCustomerResourceExtension::class]);
```
Both `extendForm()` methods run: Core's first, App's second.