Core Laravel Package

Getting Started

Angel is a Laravel-based CMS. It has now reached v1.0.0, its first production release ("tested in enough deployments to warrant a first production release"), which is a meaningful shift: the project is no longer purely pre-release code. What the release notes do not say is that the framework requirements moved — there is no mention of Laravel 5/6+ support, PHP 8 compatibility, or dependency modernization. Angel was originally built for Laravel 4.x, so before anything else, confirm the composer.json constraint at the v1.0.0 tag against your app's Laravel version. Pin v1.0.0 explicitly rather than floating.

Minimal install path:

1. composer require angel/core:^1.0 — pin the 1.0 line and read the tag's composer.json first.
2. Register the service provider in app/config/app.php under providers, and add any facade aliases the readme lists.
3. Publish assets and config: php artisan config:publish angel/core and php artisan asset:publish angel/core (Laravel 4 syntax; adapt if the 1.0 tag targets a newer Laravel).
4. Run php artisan migrate --package="angel/core" (or --path on newer Laravel).
5. Seed or create an admin user, then hit the admin route (historically under /admin) to verify the panel boots.

Where to look first: the package's service provider and routes.php — they define every URI, controller binding, and view namespace you'll interact with. After that, the migrations tell you the data model (pages, menus, users/roles), which is the real contract for extending the CMS.

First use case: stand up the admin, create one page and one menu, and confirm the public-facing route renders. That exercises the full request → controller → repository → view pipeline and will surface the most common config and binding problems before you build anything custom.

Implementation Patterns

Treat it as a modular CMS, not a library. Angel is designed so you add content types (pages, blog posts, etc.) as modules/controllers that the admin discovers. The pattern is: a controller in your app (or a companion package) that extends Angel's base admin controller, a model backed by the package's repository conventions, and Blade views in the namespace Angel expects. Mirror the shape of the built-in page/blog modules rather than inventing a new structure.

Lean on the repository layer. Angel routes data access through repository classes rather than calling Eloquent directly from controllers. Following that convention keeps your custom modules consistent with the CMS's validation, caching, and admin-form generation. If you shortcut it, you'll fight the package later.

Extend the admin via the menu/route registration hooks. New back-office sections are typically wired by adding to the admin menu and registering routes from your service provider. This is the cleanest integration point — it avoids editing vendor code and survives a composer update.

Blade theming. Public views live in a theme/view namespace. Override by publishing views to app/views/packages/angel/core/... (Laravel 4 override path) rather than editing the package. Layout/section conventions in the built-in theme are the fastest reference for building a custom one.

Menus and settings as configuration-driven content. Menus are usually stored and rendered through a helper/facade. Fetch and render them in your layout rather than hard-coding navigation — that's the intended day-to-day workflow for content editors.

Compose with other packages. Since Angel sits on Laravel, use standard service providers, events, and Blade composers for cross-cutting concerns (analytics, sitemaps, custom auth). Keep custom logic in your own package/namespace so upgrades and debugging stay tractable.

Treat 1.0 as a baseline, not a finish line. With a stable tag, the sensible workflow is to vendor the v1.0.0 source into your repo, then apply your own patches on top and track them as a diff. That gives you a known-good starting point plus a reviewable upgrade path if a 1.0.x patch ever lands.

Gotchas and Tips

• "Production release" ≠ "modern." The 1.0 note is a deployment-confidence claim, not a compatibility claim. Verify the framework and PHP constraints at the tag before planning anything; do not infer Laravel 5+ or PHP 8 support from the version bump alone.
• Version-number jump semantics. Going straight to 1.0.0 from an old pre-1.0 line means you should read the tagged source, not the historical readmes/issues — the 1.0 tag is the contract now. Anything you find in old issues may describe behavior that no longer matches.
• Maintenance cadence is still unproven. One release note does not establish a support policy. Assume no security-patch SLA and budget for forking/maintaining; vendor the package rather than relying on Packagist resolution staying stable.
• Composer conflicts are likely. Old dependency constraints (Illuminate 4.x, Symfony 2.x) will collide with modern apps. Use a dedicated legacy environment or a forked composer.json with widened constraints, and test the resolve before writing code.
• Migrations and namespace drift. Laravel 4 package migrations use --package/--bench workflows that changed in later versions. If you port Angel forward, convert migrations to standard database/migrations and adjust --path accordingly.
• Route and model collisions. Angel claims /admin and common slugs. Check your route list after install; a host app route can silently shadow an Angel route (or vice versa) depending on registration order in app.php.
• Config cache surprises. After changing Angel config, clear the config cache. In Laravel 4, stale app/config caching is a frequent cause of "my provider isn't loading" confusion.
• View override ordering. Published views only win if the package view namespace resolves your app path first. If edits "don't take," verify the override path and clear the compiled views.
• Debugging tip: the service provider and container bindings are the usual suspects. If a controller or repository can't be resolved, confirm the binding is registered and that you're not instantiating the class directly.
• Extension points: the admin base controller, the repository/validation layer, the menu registration, and Blade view overrides are the four surfaces you can extend without touching vendor code. Stay on those and keep a fork diff small.
• Testing: the release note references real deployments but ships no meaningful test suite in the repo. Write characterization tests around the routes and repository methods you actually use before upgrading PHP or Laravel — that's your only safety net, and 1.0 makes it tempting to skip.