Faq Bundle Laravel Package

Getting Started

This is a Symfony 3 bundle, not a Laravel package. Do not try to composer require genj/faq-bundle in a Laravel application: it has no Laravel service provider, no auto-discovery, and its Symfony 3 constraints will conflict with the Symfony components Laravel depends on. A Laravel developer leverages this package as a reference implementation, not as a runtime dependency.

First places to look:

1. composer.json — confirm the Symfony/PHP constraints and what the bundle actually depends on.
2. Entity/ — the Doctrine models for FAQ items/categories. This is the schema you will port to Eloquent migrations. In v2.0.0 look for the new isActive, publishAt, and expiresAt fields.
3. Controller/ — the list/detail/admin CRUD flow, plus the new search and popular-queries endpoints. This maps to Laravel resource controllers.
4. Resources/config/ — routing, service definitions, and bundle configuration.
5. Resources/views/ — Twig templates to translate into Blade components.

If you genuinely need to run the original, build a Symfony 3.4 sandbox on PHP 7.x, register the bundle in AppKernel, configure Doctrine, and import its routing. The v2.0.0 release is only marked "compatible with sf3.2", so prefer the newest 3.x you can run.

For day-to-day Laravel work, the first useful use case is: extract the FAQ schema, the scheduling/active flags, and the CRUD + search flow, then rebuild it natively in Laravel with migrations, Eloquent models, form requests, and Blade views.

Implementation Patterns

The package follows classic Symfony 3 conventions: Doctrine entities, bundle service definitions, controller actions, and Twig templates. In Laravel terms, translate each layer rather than trying to bridge containers.

Schema and models

• Port Doctrine entity fields into Laravel migrations. Expect the usual FAQ shape: question, answer, slug, category, sort order, published flag, timestamps — plus the v2.0.0 scheduling fields isActive (boolean), publishAt (nullable datetime), and expiresAt (nullable datetime).
• Replace Doctrine annotations with Eloquent $fillable, $casts, and relationships (belongsTo category, hasMany items). Cast the schedule fields: 'is_active' => 'boolean', 'publish_at' => 'datetime', 'expires_at' => 'datetime'.
• Add route model binding on the slug if the bundle uses slugs.
• Model the new visibility semantics with query scopes: an active() scope combining is_active = true AND (publish_at IS NULL OR publish_at <= now()) AND (expires_at IS NULL OR expires_at > now()). This is the equivalent of the bundle's scheduling behavior; keep it in one reusable scope so public listing and search stay consistent.

Controllers and routing

• Map Symfony controller actions to Laravel resource controllers: index, show for the public side; admin.index, admin.create, admin.store, admin.edit, admin.update, admin.destroy for management.
• Add a GET /faq/search endpoint mirroring the bundle's "very simple MySQL search" — a where('question', 'like', "%{$q}%") OR where('answer', ...) query is the direct equivalent. Do not over-engineer it: the bundle's own implementation is deliberately naive.
• Add a popular-searches view if you want the v2.0.0 analytics feature: the bundle lists the most frequent search queries, which in Laravel means a search_queries (or faq_searches) table logging the term + timestamp, then a groupBy/orderByRaw('COUNT(*) DESC') aggregation on the admin dashboard.
• Replace Symfony form types with Laravel FormRequest validation and Blade form components. Validate publish_at < expires_at when both are present.
• If the bundle exposes configurable routing prefixes, mirror that with Laravel route groups and middleware (auth for admin routes).

Views and content

• Convert Twig templates to Blade. Keep the same partial/component boundaries: category list, question accordion, answer detail, search box, results list.
• Port any YAML translation files into lang/ PHP or JSON files.
• If the bundle supports ordering, publishing, or the new scheduling flags, preserve them and add scopes such as published(), active(), and ordered().

Integration tips

• Cache the public FAQ list and popular-search aggregate; FAQ content and search stats change far less often than they are read. Invalidate the cache when an item is saved or when publish_at/expires_at boundaries pass (a scheduled job or short TTL is simplest).
• Keep the admin CRUD behind authentication and authorization policies.
• If you want to preserve the original behavior exactly, write characterization tests against the Symfony sandbox first, then port — especially around the new active/scheduling logic, which has the most edge cases (null publish, null expires, both set, expired item, future publish).
• Treat the source as an MIT-licensed specification: reuse schema and flow ideas with attribution, but do not carry over Symfony-specific coupling.

Gotchas and Tips

• Archived and unmaintained. The repository is archived. v2.0.0 adds features but does not change the maintenance picture: no security patches, no Symfony 4+ support. Do not put it in a production dependency graph.
• v2.0.0 is not a Laravel milestone. The release note says "compatible with sf3.2", confirming it targets Symfony 3.x only. The new features (scheduling fields, search, popular queries) are useful as domain reference, not as installable Laravel functionality.
• Composer conflict is likely. Laravel 8+ depends on Symfony 5/6 components. A package requiring Symfony 3 will either fail resolution or force dangerous downgrades. Do not use --ignore-platform-reqs to work around this.
• No Laravel integration points. No service provider, no facade, no config publishing, no migrations, no Blade views. Everything is Symfony bundle registration (AppKernel), Doctrine mapping, and Twig.
• Doctrine vs Eloquent mismatch. Entity mappings, annotations, lifecycle callbacks, and repository methods do not translate directly. Rebuild them idiomatically in Laravel rather than mimicking Doctrine.
• Scheduling edge cases. The v2.0.0 isActive/publishAt/expiresAt trio has ambiguous precedence — does isActive = false override publishAt, or vice versa? Read the entity/repository code to see the exact rule, then encode it once in a scope and test all combinations. Do not assume; diff the generated Doctrine SQL.
• The "search" is deliberately trivial. It is a simple MySQL LIKE query, not full-text search. If you need relevance today, use Laravel Scout or a FULLTEXT index instead of faithfully porting the naive version.
• Popular-search listing needs a write path. The bundle surfaces top queries, which implies a table recording them. Confirm where the bundle writes the log before porting its shape; you may prefer a dedicated faq_search_log model with indexes on term and created_at.
• Bundle configuration quirks. Symfony 3 bundles must be manually registered and routing imported via the bundle alias. If you run the sandbox, use bin/console debug:router and doctrine:schema:validate to inspect what is actually wired.
• Extension points are Symfony-only. Template overriding and service decoration work in Symfony; in Laravel you get the equivalent by writing your own views and bindings.
• Debugging strategy for a port: diff the generated Doctrine SQL against your Laravel migrations, then compare public output page-by-page. Keep the port covered by feature tests (including scheduling and search) so you can safely diverge from the original where Laravel conventions are better.
• Recommendation: use it as a one-time reference for FAQ domain modeling, scheduling flags, search, and admin CRUD structure, then build a small native Laravel module. The package itself should not appear in composer.json of a Laravel project.