Documentation Bundle Laravel Package

Getting Started

This package is a Symfony bundle, not a Laravel package. For a Laravel developer, that distinction drives the entire assessment: there is no Artisan install command, no Laravel service provider documented, no Blade views, and no Laravel-specific configuration publishing flow described.

Minimal starting steps:

1. Install via Composer:

   composer require pccomponentes/documentation-bundle
   

2. In a Symfony application, register the bundle in config/bundles.php.
3. Import the bundle’s routing or rely on its built-in routing/controllers, depending on the package’s documented defaults.
4. Configure the documentation content source and confirm the documentation route renders.

Where to look first:

• DocumentationBundle.php — the bundle entry point and the file changed in v1.4.4. Start here to understand service wiring and extension configuration.
• The bundle’s DependencyInjection extension and routing/controller classes.
• Its Twig templates, since the package advertises template overrides.
• Composer metadata for Symfony version constraints and autoloading details.

First use case: serving version-controlled project documentation from inside a Symfony application instead of a separate static docs site. Add a small docs/ directory with an index page and one or two Markdown files, configure the source path, and verify the documentation route.

For a Laravel application specifically, do not assume php artisan vendor:publish exists or that Laravel auto-discovers the package. A Laravel integration would require manual wiring of Symfony bundle services, routing, and likely Twig-to-Blade adaptation. That is not a day-one drop-in workflow.

Implementation Patterns

• Symfony-native registration: Treat this as a normal Symfony bundle. Register it, configure it through the bundle extension, and import its routes if they are not loaded automatically.
• Docs-as-code layout: Keep Markdown files in a repository directory such as docs/. If the bundle maps folders to navigation, use subdirectories to create a hierarchy rather than inventing custom menus.
• Configuration-first customization: Set the content source path, route prefix, and any environment restrictions in bundle config. Avoid modifying vendor files; use configuration and template overrides.
• Twig template overrides: Publish or override the bundle’s templates so documentation inherits the host application’s layout, navigation, and styling. This is the expected customization path for matching an existing Symfony app.
• Route protection: If documentation is internal, put the documentation route behind the host application’s authentication or restrict it by environment. Do not rely on the bundle to provide access control.
• CI usage: Lint Markdown and validate links in CI. Because docs live beside code, review documentation changes in the same pull requests as application changes.
• Laravel bridge, only if justified: A Laravel integration would mean creating a service provider that registers the bundle’s services manually, adapting Symfony routing/controllers to Laravel’s router, and replacing Twig templates with Blade equivalents. This is a maintenance project, not a normal package install. Prefer a Laravel-native documentation package unless there is a strong reason to reuse this bundle.

Gotchas and Tips

• Not Laravel-native: There are no documented Artisan commands, Laravel config publishing, Blade views, or Laravel middleware integration. Budget significant effort if you attempt to use it in Laravel.
• Very low adoption signal: Zero stars and zero dependents mean little community validation. Expect to read the source rather than rely on examples or Stack Overflow answers.
• Sparse documentation: The provided material includes only a short description and a patch release note. Verify behavior directly in the bundle classes and templates before designing around it.
• Maintenance risk: The last release is from December 2023, and v1.4.4 appears to be a small patch. Check open issues, Symfony version compatibility, and PHP version constraints before adopting it.
• Route conflicts: The built-in documentation route can collide with catch-all routes or existing prefixes. Inspect routes with bin/console debug:router in Symfony, or php artisan route:list only after a Laravel bridge is in place.
• Cache behavior: After changing bundle configuration or adding documentation files, clear the Symfony cache with bin/console cache:clear. If the bundle caches a documentation tree, stale navigation is a likely debugging symptom.
• Markdown rendering differences: Tables, footnotes, raw HTML, and syntax highlighting may depend on the underlying parser and its safe-mode configuration. Test representative documentation early.
• Filesystem visibility: Ensure the web server can read the configured docs directory. Permission failures often present as missing pages or 404s rather than explicit permission errors.
• Debugging service wiring: Use bin/console debug:container and inspect DocumentationBundle.php when services are missing. The bundle entry point is the most reliable place to understand compiler passes and extension configuration.
• Upgrade note: v1.4.4 appears to be a patch-level update over v1.4.3 with no indicated breaking changes. Still verify Composer constraints and run the application test suite after upgrading.