Cms Laravel Package

Getting Started

1. Confirm access and stability first. basedigital/cms is a private Bitbucket package with no public stars, dependents, or Packagist metadata. Before wiring it into a project, verify you can authenticate to bitbucket.org/basewd/basecms, check the latest tagged release, and confirm the Laravel/PHP versions it supports. Add the VCS repository to composer.json and require a pinned tag rather than dev-master.
2. Install and publish. Run composer require basedigital/cms, then inspect the package service provider for publishes() calls. Expect to publish config, migrations, views, and possibly frontend assets. Run php artisan vendor:publish --provider="Basedigital\Cms\CmsServiceProvider" (confirm the actual provider namespace from composer.json/src).
3. Read the service provider and routes first. In an undocumented private CMS package, the service provider is the real documentation. Look for route registration, middleware groups, Blade directive registration, model bindings, and config keys. Then inspect routes/ and src/Http/Controllers/ to understand the admin and public surface area.
4. First use case: a simple managed page. Create a page through the package’s admin routes or model, confirm the public route resolves, and render it in a Blade view. This validates installation, routing, persistence, and view integration in one pass before you attempt menus, media, or localization.

Implementation Patterns

• Treat the package as a content substrate, not an application framework. Use its models and admin screens for pages/posts/media, but keep your domain logic in your own app services. Avoid editing vendor files; extend via published config, view overrides, and model subclasses where the package allows it.
• Wrap CMS reads behind your own repository or presenter layer. Instead of calling package models directly from controllers and Blade everywhere, create PageRepository or view models. This isolates you from package API changes and makes caching, fallback content, and testing easier.
• Use route model binding and explicit route groups. If the package registers catch-all public routes, place your application routes before the CMS catch-all or configure the package’s route prefix. For admin integration, mount the CMS under a dedicated middleware group with your auth/authorization stack.
• Blade integration pattern. Prefer package-provided Blade directives/components for rendering menus, media, and editable regions. If directives are not documented, inspect the service provider for Blade::directive() calls. Create thin wrapper components in resources/views/components/cms/ so templates do not depend directly on package syntax.
• Admin CRUD workflow. Use the package’s admin controllers for editorial CRUD, but add your own form requests, policies, and validation around them if the package’s defaults are too permissive. For custom content types, check whether the package supports configuration-driven templates or whether you need to extend its models and register your own admin routes.
• Media and file handling. Centralize uploads through the package’s media model/service if present, but add your own storage disk configuration and image conversion pipeline. Do not let editors upload directly to public disks without validation and sanitization.
• Caching pattern. Cache rendered CMS fragments and menu trees, keyed by content ID, locale, and updated timestamp. Invalidate via model observers on the package’s content models, or clear tagged caches on save. This is usually the highest-leverage day-to-day optimization for a CMS package.
• Localization and multi-site. If the package supports locales or sites, drive it from config and middleware. Keep locale/site resolution in your app’s middleware, then pass the resolved context into CMS queries rather than relying on implicit session state.
• Testing pattern. Write feature tests against your own routes that hit the CMS, using factories if the package provides them. If factories are missing, create test helpers that seed pages/menus directly. Mock media storage with Storage::fake() and assert rendered output rather than internal package calls.

Gotchas and Tips

• Private VCS dependency friction. Every CI runner, developer machine, and deployment target needs Bitbucket credentials or an SSH key. Prefer a Composer auth configuration or a satis/private Packagist mirror. Pin to a commit or tag; dev-master on a private CMS package is a production risk.
• Sparse documentation is the main cost. Expect to reverse-engineer behavior from source. Start with src/Providers, routes/, config/, and migrations. Keep a local notes file of discovered config keys and extension points for your team.
• Route collisions. CMS packages often register broad public routes such as /{slug}. Register your app’s explicit routes first, configure the CMS route prefix, and test 404/route-order behavior. In Laravel, later routes win only if earlier ones do not match, so ordering matters.
• Migration ordering and publishing. Publish migrations before running migrate, and check whether the package expects its migrations to run before or after your app’s. If the package uses polymorphic or media tables, foreign key constraints can fail on fresh installs if ordering is wrong.
• Config caching quirks. After changing published config, run php artisan config:clear. If the package reads config at service-provider boot time, cached config can mask changes. Also check for environment-specific keys that must exist in .env.
• View override strategy. Laravel package views are usually overridden by placing files under resources/views/vendor/{package-name}. Confirm the package’s view namespace from the service provider. Override only the views you need and keep a changelog when updating the package.
• Asset publishing. If the admin UI ships compiled assets, re-publish after upgrades and clear browser caches. If assets are not versioned, add a cache-busting query string or your own asset pipeline.
• Authorization is usually your responsibility. Do not assume the CMS admin routes are protected beyond package defaults. Wrap them in auth and policy middleware, and audit any public preview or draft-preview routes.
• Extension points to inspect. Look for contracts/interfaces, model events, Blade directives, config-driven content types, and middleware registration. These are safer integration points than subclassing controllers. If none exist, prefer decorating services over monkey-patching.
• Upgrade discipline. Because the package has no dependents and little public usage, regressions are less likely to be caught by the community. Read the diff between tags, run your CMS feature tests, and test admin CRUD and public rendering after every upgrade.