Cms Laravel Package

Getting Started

• Install with composer require numberninecms/cms and confirm the PHP/Laravel version constraints in composer.json. The package service provider is auto-discovered.
• Publish config and assets, then migrate:

  php artisan vendor:publish --provider="NumberNine\Cms\CmsServiceProvider"
  php artisan migrate
  

  Check the published config file first — it typically controls route prefix, middleware, storage disk, and module registration.
• Look at the package routes (php artisan route:list) to find the admin entry point (commonly /admin or a configurable prefix), then log in with a seeded/admin user.
• First end-to-end use case: create a page or block in the admin UI, assign it to a route or template, and render it in a Blade view. This validates installation, routing, persistence, and view integration in one pass. After that, add a custom field or module to confirm the extension workflow.

Implementation Patterns

• Treat the CMS as a content repository rather than a full application framework. Resolve pages/blocks through the package’s models or repositories, then render them in your own controllers and Blade templates. Keep presentation logic in views/components, not in CMS config.
• Admin-driven content workflow: define page templates and reusable blocks in the admin, then expose them to Laravel via the package’s rendering helpers or view composers. This keeps editors productive without requiring deploys for content changes.
• Request handling: when writing custom admin forms, API endpoints, or middleware that inspects CMS submissions, read the full payload with $request->all() (the behavior corrected in 0.4.5). Use $request->validated() for persistence and $request->file() explicitly when handling uploads.
• Module/extension pattern: register custom modules or blocks through the package’s config array or service provider hooks, implementing the expected interfaces. Use the package’s existing modules as reference implementations.
• Routing and middleware: mount the CMS admin behind auth/role middleware, keep public content routes separate, and cache routes only after clearing config cache in production.
• Version pinning: during 0.4.x, pin to a minor version (e.g. 0.4.*) and review the changelog before upgrading. Run smoke tests for admin forms, uploads, and page rendering after each update.

Gotchas and Tips

• Pre-1.0 API churn: 0.x releases can change method signatures and config keys. The 0.4.5 fix (all() instead of get()) is a reminder that request-shape assumptions can shift; audit any custom code that reads request arrays directly.
• $request->get() vs $request->all(): get() returns input data only and can miss uploaded files or merged request data. all() returns the full input array including files. If custom form or upload code relied on get(), switch to all() or use input()/file() explicitly.
• Stale caches: after changing CMS config, registering modules, or updating the package, run php artisan config:clear and php artisan route:clear. “My module/page isn’t showing” is frequently a cached config or route issue.
• Media and uploads: verify the configured storage disk and run php artisan storage:link. Missing files usually indicate a disk mismatch or missing symlink rather than a code bug.
• Debugging: use php artisan route:list to confirm admin/public routes, Laravel logs or Telescope for request payload issues, and a temporary test route that dumps $request->all() to see exactly what the CMS receives.
• Extension points: publish and override config instead of editing vendor files. Keep custom modules in app/ or a separate package so they survive composer update. Prefer package events/hooks or decorators over patching core classes.
• Upgrade path: read the compare link for each release. For 0.4.5 the change is internal, but retest file-upload and multi-field form flows after upgrading to confirm request data is still captured as expected.