Getting Started

This is a Symfony bundle, not a Laravel package. In a Laravel codebase, first confirm whether you actually need it; the official Laravel agent is usually the better fit. Use this package when you maintain a Symfony service alongside Laravel, or when you bridge a Symfony kernel for the admin API.
Install with Composer: composer require forestadmin/symfony-forestadmin. Check the package's composer.json for Symfony/Doctrine version constraints before upgrading.
Register the bundle in config/bundles.php (Symfony) or in your bridge kernel. Laravel does not auto-discover Symfony bundles.
Configure FOREST_AUTH_SECRET, FOREST_ENV_SECRET, and the Doctrine database connection. The package uses Doctrine ORM, not Eloquent.
Run the package's install/setup command (check bin/console list forest after registration) to create the Forest Admin user tables and initial configuration.
First use case: expose a read-only Doctrine entity as a collection, open the Forest Admin UI, and verify CRUD. In v1.2.0, evaluate the new native query capability for ad-hoc reporting, but enable it deliberately and with a restricted database user.

Implementation Patterns

Model admin collections on Doctrine entities. Map existing tables with Doctrine attributes/XML instead of duplicating Eloquent models.
Use a separate database user for Forest Admin. For native query support, create a role with SELECT only on reporting schemas and no write permissions.
Enable the native query capability explicitly per environment. Treat it as opt-in: useful for analytics and reporting, not for application writes.
Prefer smart actions and custom action routes for controlled operations such as refunds or status changes. Reserve native queries for read-only exploration and scheduled reports.
If you are a Laravel developer supporting a Symfony admin service, keep the Laravel and Symfony apps on the same database but separate deployments. Do not try to mount the Symfony bundle inside Laravel's HTTP kernel.
For local development, point the bundle at a read replica or a seeded SQLite/MySQL database and use development environment secrets, not production secrets.
Add health checks for the Forest Admin API endpoints and log authentication failures so UI issues are distinguishable from backend errors.

Not a Laravel package: no service provider, no config/forest.php, no Eloquent integration. Expect Symfony DI, Doctrine, and Symfony console commands.
Native query is powerful and risky: raw SQL runs with the configured database user's permissions. Use a read-only user, restrict by schema, and audit usage. Do not enable it in production until permissions are tested.
Capability configuration is easy to miss. If native query does not appear in the UI, check the bundle's capability block, clear the Symfony cache, and inspect the resolved config.
Doctrine mapping drift is common when exposing existing Laravel tables. Start with a small set of tables and explicit column mappings before expanding collections.
Authentication mismatches between FOREST_AUTH_SECRET and FOREST_ENV_SECRET often look like CORS failures. Check the browser network tab and Symfony logs before changing CORS settings.
Ensure the API allows the Forest Admin origin if the admin UI is hosted by Forest Admin.
Pin Symfony and Doctrine versions in Composer and test v1.2.0 in staging; a feature release can still expose dependency constraints.
Debug with Symfony's profiler, the bundle's debug:config command, and var/log for Doctrine query errors.
Use extension points such as custom actions, decorators, and capability overrides for behavior changes. Avoid forking the bundle to customize query handling.