East Common Laravel Package

Getting Started

Before installing, verify php -v reports 8.4 or newer — the package sets this as a hard composer platform requirement, and Composer will refuse to resolve on 8.3.

composer require teknoo/east-common

Where to look first, in order:

1. infrastructures/symfony/ — if you're on Symfony, this is where the Teknoo\East\CommonBundle lives. Register it in config/bundles.php and let its DependencyInjection/ extension wire the services. This saves you from hand-assembling the container.
2. src/ — the domain contracts. Start with the user-management interfaces (user entity, user provider, storage) and the persistence abstractions. These are the extension points you implement.
3. infrastructures/doctrine/ — the concrete persistence layer. Note it targets MongoDB ODM, not relational Doctrine, so confirm this matches your stack before committing.
4. agents/AGENTS.md and the Makefile — the project's own conventions and validation commands, useful for matching style and running checks locally.

First useful use case: user management. The typical wiring is (a) extend the provided base user document with your own fields, (b) register it against the Doctrine ODM mapping, and (c) let the bundle's services handle lookup/creation. Once a user can be persisted and fetched, layer object persistence (Flysystem-backed file storage, template rendering) on top rather than starting with assets.

Implementation Patterns

Split domain from adapters. The whole point of East is that Teknoo\East\Common\ (domain) has zero knowledge of Teknoo\East\CommonBundle\ (Symfony) or Teknoo\East\Common\Doctrine\ (persistence). Write your application code against the src/ interfaces and bind concrete adapters through the container — this is what makes the package testable and swappable.

Container-first construction. Services are built via constructor injection; there is no service locator. Under Symfony, rely on the bundle's service definitions and autowiring. Under plain PHP-DI, load the package's service definition files (services.php / equivalent) and merge into your container, then override the adapter bindings you want to replace.

User management flow. Implement your user class on top of the package's base document/interface, give Doctrine ODM the mapping, then inject the package's user-related services (authentication, lookup, creation) into your controllers/messaging layer. Keep controllers thin — the East style pushes logic into services rather than fat actions.

Persistence pattern (MongoDB ODM). Extend the base documents rather than creating parallel ones, so the package's repositories and queries keep working. Use #[ODM\Document]-style attributes consistently with the package's own mappings; mixing mapping styles across a single collection is where most confusion starts.

Files via Flysystem. Uploads (avatars, attachments) go through the Flysystem adapter under infrastructures/flysystem/ rather than move_uploaded_file. This delegates storage to League Flysystem and lets you swap local disk for S3/anything without touching domain code.

Templates via Symfony UX. Rendering is wired through Twig/TwigComponent and LiveComponent. Treat templates as infrastructure — the domain should emit view models, not HTML.

Assets via the minify adapter. CSS/JS bundling uses matthiasmullie/minify through infrastructures/minify/. Register your asset groups there rather than adding a separate pipeline; two pipelines fighting over the same output directory is a common source of stale-cache bugs.

Gotchas and Tips

• PHP 8.4 is non-negotiable. If your CI image or local box is on 8.3, install fails before you get a single error message about the actual library. Pin the runtime first.
• It's MongoDB ODM, not ORM. Readers coming from Doctrine ORM assume relational; this package does not. If you're on PostgreSQL/MySQL, the persistence components are largely inapplicable — you'd implement your own adapters against src/ interfaces.
• Two namespaces, one package. Teknoo\East\Common\ vs Teknoo\East\CommonBundle\ (and further …\Common\Doctrine\, …\Common\Flysystem\). Confusing them is the most common autoload/import error; check the file's location under src/ vs infrastructures/ when an import "doesn't exist".
• Bundle registration is silent when missing. If services you expect aren't available, the bundle isn't loaded in config/bundles.php. There's no loud failure — you just get "service not found" later.
• Version-lock the East stack together. east-common depends on teknoo/east-foundation and teknoo/recipe; mismatched minor versions cause subtle DI/service definition breakage. Install them in one composer require and commit composer.lock.
• Debugging goes through the Makefile. Use make test (PHPUnit + Behat) and make qa (PHPStan, PHPCS, composer audit) — these are the project's own gates and will reproduce CI locally. make qa-offline skips the network-dependent audit.
• Extend, don't patch. With only 2 stars and 0 dependents, you are effectively the maintainer of any fork. Keep customizations in your own adapters implementing src/ interfaces; modifying vendor/ will be lost on the next composer update.
• Expect low community support. Sparse docs, few eyes on issues. Budget reading source in src/ and infrastructures/ directly — the AGENTS.md conventions give you the map, but specifics need the code.
• Static analysis will catch DI wiring mistakes early. PHPStan is configured strictly; run make qa before writing tests to surface container/type problems, then add Behat scenarios for the end-to-end flows you actually ship.