Portfolio Bundle Laravel Package

Getting Started

First, a reality check before you composer require anything: stfalcon/portfolio-bundle is a Symfony2 bundle, not a Laravel package. There is no service provider, facade, migration set, config-publish command, or artisan integration. If you're on Laravel, this package does not install-and-run — you would be reading it as a reference implementation and re-building its entities/controllers/views natively. It only integrates directly if you are maintaining a legacy Symfony 2.x/3.x app that wants a ready-made "projects + images" module.

For a Symfony legacy app (the only direct-install path):

1. composer require stfalcon/portfolio-bundle — expect it to pin old symfony/*, doctrine/orm, and twig/twig constraints. Check composer.json before you start; resolution failures are the most likely first blocker.
2. Register in app/AppKernel.php: new Stfalcon\Bundle\PortfolioBundle\StfalconPortfolioBundle().
3. Import its routing in app/config/routing.yml under a prefix you control (e.g. /portfolio).
4. Let Doctrine pick up the bundle mappings, then doctrine:schema:update --dump-sql (inspect first), or generate a migration.
5. Register the admin service if you want the Sonata-era admin UI for CRUD.

Where to look first: Resources/config/ (routing, services, Doctrine mapping) and Entity/. Those define the real model names — Project, and however images/media are attached — and what is actually configurable. Treat README.md as stale; it predates modern Symfony conventions.

First vertical slice: stand up the public listing route, create one project (title, slug, description, image), confirm the detail page renders with images. Only then wire the admin side or start overriding templates. If you're porting to Laravel instead, the equivalent slice is: Eloquent Project + ProjectImage models, migrations mirroring the bundle schema, a resource controller, and a Blade listing/detail — roughly 3–5 dev-days for a tested equivalent (that number is the real cost of "free").

Implementation Patterns

Extend the data model, not the bundle internals. The old Symfony2 idiom was to subclass bundle entities from your app bundle; avoid it if you can. On anything modern, declare your own entity mapped to the same table, or fork. For a Laravel port, translate the entities into Eloquent models and normalise images into a project_images table with a project_id foreign key plus an order column — the bundle models "multiple images per project," so keep that cardinality intact in your migration.

Override templates, don't edit vendor. On Symfony, the intended customisation point is dropping Twig files into app/Resources/StfalconPortfolioBundle/views/.... That's the clean way to change listing markup, image sizing, and meta tags. In a Laravel port, this maps to a resources/views/portfolio/ set of Blade views with a layout you own — no overriding machinery needed.

Keep query logic in a repository, not the controller. Use (or subclass) the project repository for listing, category filtering, and ordering so the listing page, homepage tiles, and any widgets share one query contract. In Laravel this is a scoped Eloquent query or a ProjectRepository class — resist scattering orderBy clauses across controllers.

Embed blocks via sub-requests, and cache deliberately. For a "latest projects" sidebar, render with a Twig render(controller(...)) sub-request (or, in Laravel, a view composer / Blade component that pulls the repository). This bundle predates Symfony's cache contracts, so there is no automatic tag-based invalidation on project edits — you own that. Either skip caching for low-traffic portfolio pages or explicitly clear the relevant cache key on save. Don't assume "it just invalidates."

Split admin from frontend. The pragmatic workflow is an admin bundle (Sonata-era) for create/edit/publish/image upload, and the bundle's frontend controller for display. Confirm how images are modelled (separate entity vs. embedded collection) before hooking uploads — and hook your upload handling into the admin form, not the frontend path. For a Laravel port, this is exactly where Filament/Nova earns its keep: free CRUD, ordering, and image uploads you don't have to write.

Preserve the URL/slug contract on port. If public portfolio links are already indexed, keep the bundle's slug/URL shape in your reimplementation rather than inventing new routes — otherwise you're issuing redirects or eating a rankings hit.

Gotchas and Tips

Framework mismatch is the headline. Do not attempt a shim that loads Symfony 2 container/autoload components inside Laravel to "reuse" the bundle. Container and autoloading contracts don't reconcile; the hybrid is unmaintainable. Port the schema and behaviour, discard the code.

Composer resolution failure is your most likely first error. The bundle's pinned Symfony 2 / Doctrine / Twig constraints will conflict with modern symfony/symfony, doctrine/orm, and PHP 8.x. If composer require explodes, that's expected — it's a signal about the target framework, not a bug to fight.

Doctrine annotations are a trap on modern stacks. Annotation-driven mapping is deprecated/removed in current ORM, and Twig 1.x syntax (deprecated tags/filters) will break on Twig 2/3. If you fork onto a modern Symfony, budget a rewrite of metadata and templates, not just a PHP-version bump.

Security posture. Inherited Symfony 2 transitive dependency CVEs will likely fail a modern SCA gate. A portfolio page is low-criticality, but if your CI enforces vulnerability scanning, this package will trip it — plan a documented exception or exclude it from the approved dependency list.

Zero upstream activity, zero dependents. 17 stars and 0 dependents means no community to escalate to and no downstream validation that it ever resolved cleanly in the wild. Treat it as fork-and-own: audit the code, name an owner, write a short README on your internal divergences, and add tests so the fork doesn't become opaque if the original author of the port moves on.

Config quirks. Configuration is "standard Symfony bundle settings" — meaning config.yml under stfalcon_portfolio: with whatever the bundle's DependencyInjection/Configuration.php exposes (and nothing more). Read that file to know the actual keys; don't assume knobs exist. There's no vendor:publish equivalent.

Media pipelines are on you. The bundle handles basic upload/multiple-images-per-project, but it does not meaningfully solve responsive derivatives, object storage, or CDN delivery. Those are the real scaling concerns for a portfolio surface — wire them independently (e.g. Glide/Intervention in Laravel, LiipImagine if you stay on Symfony).

Extension points that actually exist (vs. what you'll need to build): template override dir, Doctrine entity/repository subclassing, and service overrides via DI. What it does not give you: cache invalidation, SEO/schema markup, localisation, editorial workflows, or a modern admin UI. If your requirements touch any of those, that's your build-in-house signal.