Train Category Bundle Laravel Package

Getting Started

The 0.0.1 release ships with no notes beyond a link to the commit history, so treat the source itself as the documentation. Before writing any code, spend ten minutes on reconnaissance:

1. composer require tourze/train-category-bundle in a throwaway project (not your app) and inspect what lands in vendor/tourze/train-category-bundle.
2. Read composer.json first. The key things to look for are the type field (symfony-bundle means this was never written with Laravel in mind), the require block (any symfony/* or doctrine/* entries tell you immediately whether you can consume it natively or need a bridge), and the autoload PSR-4 prefix so you know the namespace.
3. Look for a *Bundle.php class, a DependencyInjection/ directory, and Doctrine mapping files or attributes. If those exist, this is a Symfony bundle and Laravel's package discovery will ignore it entirely — no service provider, no vendor:publish.
4. Check for src/Entity/, src/Repository/, and any migration or schema files. The category model is the part you actually care about; the framework wiring around it is incidental.

The first realistic use case is a category tree for train products — route types, train grades (high-speed, intercity, sleeper), or ticket classifications — that you want to store once and hang your own Eloquent models off. Start by proving you can read the schema and instantiate the model, not by trying to boot the bundle inside Laravel.

Implementation Patterns

Consume the model, not the bundle. In practice you rarely want the Symfony container wiring inside a Laravel app. Pull the domain classes in as a plain library dependency, and let your own service layer own the persistence. Wrap the package's entity in your own repository or action class so the rest of your app never imports a Tourze\... type directly — this is what makes the eventual 0.1.0 rename cheap instead of a refactor.

Mirror the schema into a Laravel migration. If the package ships Doctrine mappings, transcribe the table and columns into a normal Laravel migration and keep it in your repo. Do not rely on the package to create tables; a 0.0.1 dependency should not be issuing DDL against your database.

Treat categories as reference data. A category tree is closer to a lookup table than to user content. Seed it from a config file or an artisan command, cache the flattened tree, and invalidate on write. This keeps the package on the cold path — a category change happens monthly, a page render happens thousands of times an hour — which is exactly where an unproven dependency is safest.

Adapter pattern for tree queries. If the package provides a repository with tree-walking methods, call it behind an interface you define. If it doesn't, write recursive CTE or adjacency-list queries yourself against the mirrored table. Either way your application code depends on CategoryTreeQuery, not on the vendor class.

Pin and isolate. Require an exact version ("tourze/train-category-bundle": "0.0.1"), and keep the integration surface in one or two files. A single adapter file is the difference between a five-minute upgrade and an afternoon of archaeology when 0.0.2 lands.

Gotchas and Tips

• vendor:publish will not find it. No Laravel service provider means no publishable config, views, or migrations. Anything you need to customise, you copy into your own config/ or database/migrations/ by hand.
• Symfony dependencies leak into your container. If the require block pulls symfony/framework-bundle or symfony/dependency-injection, you are adding a second framework's worth of packages to a Laravel app. Run composer why symfony/dependency-injection after install and decide whether that is acceptable; often it is not, and copying the handful of entity classes is the better trade.
• 0.0.1 is a placeholder version, not a stability promise. Semver treats 0.0.x as "anything may change." Assume class names, namespaces, and table names are all in flux. Do not build a public API on top of these types.
• Doctrine vs Eloquent impedance. Doctrine entities use setters, proxies, and a unit-of-work; Eloquent expects attributes and its own query builder. You cannot mix them on the same model. If you hydrate the package's entity, you are committing to Doctrine's EntityManager for that slice of the app — usually not worth it for one table.
• Debugging missing classes. composer dump-autoload -o and php -r "var_dump(class_exists('Vendor\\Ns\\ClassName'));" will tell you in seconds whether you have a namespace typo or a genuinely absent class. Do this before assuming the package is broken.
• Read the commit log, since the release notes are empty. For a 0.0.1 the entire history is the spec: file layout, test coverage (or its absence), and whether the author is still pushing. No tests on a data-model package means you should write your own around the mirrored schema.
• Extension point is the schema, not the code. The stable interface here is the category table. Own the table, own the queries, and the package becomes an optional source of type definitions rather than a runtime dependency you cannot remove.