Core Bundle Laravel Package

Getting Started

Understand the artifact before writing any code. elcodi/core-bundle is a read-only subtree split of the elcodi/elcodi monorepo, published so each component/bundle can be required individually. It accepts no PRs or issues by design. The source of truth — releases, tags, changelog, contribution — lives upstream. If you are debugging behaviour, read the upstream monorepo, not this mirror.

Decide your entry point first, because there are only two real ones:

1. You maintain a legacy Elcodi/Symfony app. Then this is a normal dependency. Start by reading the ElcodiCoreBundle class and its DI extension in src/, and the service definitions under src/Resources/config/. This bundle is the "core" layer the rest of Elcodi boots against: context services (currency, language, locale), shared configuration, entity/manager wiring, and event hooks.
2. You are on Laravel and want the e-commerce concepts. Do not add this to composer.json. It is a Symfony bundle — its unit of distribution is a Bundle class plus kernel-registered DI extension and compiler passes. There is no Laravel ServiceProvider equivalent that wires that. Treat it as design reference material, not a dependency.

Minimal first steps (Laravel dev, evaluation path):

# Throwaway Symfony project at the Elcodi-era PHP version — NOT your Laravel app.
mkdir elcodi-spike && cd elcodi-spike
composer init --no-interaction
composer require elcodi/core-bundle

If Composer resolution fails (it likely will on PHP 8.1+/Symfony 6/7), stop — do not try --ignore-platform-reqs. Record the failure as your finding and fall back to reading the source.

First use case: inventory the domain concepts. Grep the service definitions for currency, tax, cart, order, and pricing services, and read the corresponding interfaces in the sibling Elcodi component packages. That inventory — not the code — is what you take to a Laravel port or a build decision.

Pinning: the README tells you to use the last stable tag for stability, or dev-master to ride the tip. In a legacy setup, pin an exact tag and commit the lock file; there is no upstream patch stream you can rely on.

Implementation Patterns

Pattern 1 — Native Symfony consumption (legacy maintenance only). Register the bundle in AppKernel/bundles.php, import its config under the extension's root key, then consume it through the container rather than instantiating services by hand. Customize via configuration and, where the core is rigid, a compiler pass in your own bundle. This is the intended path and the only one that is not a port.

Pattern 2 — Concept port to Laravel (recommended if you want the domain). Do not bridge kernels. Extract and re-express:

• Value objects and context (money, currency, locale, tax rules) → plain PHP classes in app/Domain/Commerce/… with no framework imports. They are the part worth keeping and the part that tests fastest.
• Domain entities / state transitions (cart → order, checkout steps) → Eloquent models plus explicit state methods or a small state machine; keep transitions out of controllers.
• Service wiring → bind interfaces to implementations in a ServiceProvider. This is the piece that replaces the Symfony DI extension; keep it thin and declarative.
• Events → map Elcodi's event names one-for-one onto Laravel events/listeners so behaviour stays traceable during the port, then rename if you like.

Pattern 3 — Service boundary. If you genuinely need an Elcodi-era capability running, run it as a separate Symfony application and integrate over HTTP or a queue. This is a service boundary, not a library adoption, and it avoids fighting two kernels in one process.

Pattern 4 — Spike-and-retire. A short, disposable install to answer "does it even resolve?" against your target PHP/Laravel versions. Its only output is a documented rejection. That is a legitimate deliverable and cheaper than a half-finished integration.

Cross-cutting tips:

• Keep the port in an internal Composer package (app/Domain extracted to acme/commerce-domain) so it is versioned and testable independently of the host app.
• Port in this order: value objects → context services → persistence → event wiring. That ordering lets you test domain logic without a database.
• Use Symfony's debug:container and debug:event-dispatcher when reading the legacy app to confirm which service IDs and events actually exist at runtime rather than trusting docs.

Gotchas and Tips

Framework mismatch is the default, not the exception. Elcodi assumes Doctrine entities, Symfony's event dispatcher lifecycle, bundle configuration trees, and kernel boot ordering. None of that maps onto Laravel's HTTP kernel, container, or Eloquent without a shim that would become the largest and least-documented part of your app. Any estimate that assumes "it installs like a normal Composer package" is wrong.

Composer will usually refuse. Symfony 2.x components, older Doctrine, and legacy PSR constraints collide with what modern Laravel pulls in. Resolve this in a throwaway project first — it is the cheapest failure to discover. Do not use --ignore-platform-reqs; it converts a clean install error into a runtime failure you will chase for days.

PHP 8+ silent breakage. Expect removed functions, dynamic-property deprecations, and type-juggling changes that pass code review but fail at runtime. If you must run it, pin the PHP version in a container that matches the era.

Octane and worker reuse. Symfony 2/Doctrine-era container and ORM assumptions do not survive persistent workers. Even in a separate-process integration, do not assume request-scoped state is reset correctly.

Read-only distribution. No PRs, no issues, no releases from this repo. Every fix is a fork you own. Do not build a team process around upstream responsiveness for this artifact.

Don't misread the health score. 0 stars / 0 dependents / "readme" maturity are artifacts of the subtree split, not evidence about the parent project. Treat the score as uninformative, not as a disqualifier — the disqualifier is the framework mismatch and the absence of a maintenance path for this artifact.

The docs are unreliable. elcodi.io, Gitter, and the Twitter handle in the README predate the current stack and should be assumed dormant. Support level is effectively "read the source." Validate any link before relying on it.

MIT licensing is the one clean signal. No legal friction, so using it as reference material (reading the code, copying patterns) is fine; the constraint is engineering, not law.

Extension points, if you are in Symfony: the bundle's DI extension (config root key, aliases) and its compiler passes are where legitimate customization lives. Prefer a small app-level compiler pass over forking the bundle; when you do fork, keep the diff minimal and tag it so composer.lock is meaningful.

Scope-creep guard. The failure mode is starting with "just the currency helper" and ending with a partial Symfony kernel inside a Laravel app. If the port grows beyond value objects and a repository layer, stop and reconsider build-vs-buy.

When in doubt, the answer is "reference only." Run the one-day spike, document why it was rejected, harvest the domain model, and choose an actively maintained Laravel-native alternative or build the narrow slice you actually need.