Titan Laravel Package

Getting Started

Titan is an opinionated Laravel application skeleton — frontend pages plus a full admin backend — rather than a single-purpose library. Treat it as a framework you install once and then extend, not a package you sprinkle into an existing app.

Minimal setup:

composer require bpocallaghan/titan
php artisan vendor:publish --provider="Bpocallaghan\Titan\TitanServiceProvider" --tag=config
php artisan vendor:publish --provider="Bpocallaghan\Titan\TitanServiceProvider" --tag=migrations
php artisan vendor:publish --provider="Bpocallaghan\Titan\TitanServiceProvider" --tag=assets
php artisan migrate
php artisan db:seed --class="Bpocallaghan\Titan\Database\Seeds\TitanSeeder"

On Laravel 5.5+ the service provider is auto-discovered; on older versions register it in config/app.php. After seeding you should have an admin user (check the seeder for the default credentials — change them immediately) and a working /admin login.

Where to look first, in order:

1. config/titan.php (published) — this drives almost everything: admin prefix, middleware, enabled modules, upload paths, frontend theme.
2. The published routes/ files — Titan typically splits web.php (frontend) and admin.php (backend). This is the map of what you get out of the box.
3. resources/views/vendor/titan/ after publishing views — the admin layout and Blade partials are your extension points.
4. The package's base controllers (AdminController, FrontendController) — you'll extend these rather than Controller.

First real use case: log into /admin, confirm the dashboard renders and the nav is populated, then scaffold one CRUD module (e.g. a Photo or Article section) end to end — migration, model, admin controller, admin views, menu entry — before touching anything else. That single vertical slice tells you whether the package's conventions match your project.

Implementation Patterns

Extend the package base classes, don't fight them. A typical admin controller subclasses Titan's admin controller and declares its model, views, and validation rules. That base class usually handles the index listing, create/edit forms, delete, and flash messaging, so your controller stays small:

class ArticlesController extends AdminController
{
    protected $model = Article::class;
    protected $view  = 'admin.articles';
    protected $route = 'admin.articles';
}

Check the parent's protected properties before writing your own store/update methods — you'll often only need $rules and $uploadFields.

Route registration. Keep your app routes in the same files Titan publishes and mirror its grouping. Admin routes belong under the package's admin prefix and middleware group (auth + role/ability check), not in a fresh Route::group you invent — otherwise nav highlighting, breadcrumbs, and permission checks desync.

Models: use the package traits. Titan-era frameworks ship traits for the recurring concerns: slug generation, image/file uploads with thumbnail variants, publish/active flags, and soft deletes. Apply these traits and follow their naming expectations for the upload column (image, photo, file) rather than inventing your own — the admin form partials and the upload handling in the base controller look for specific attribute names.

Menu and navigation. Navigation is usually config- or database-driven. Small sites: add entries to the published nav config. Larger sites: a Menu/Nav model with an admin CRUD and a view composer that injects the tree into the frontend layout. Pick one and be consistent — mixing both is a common source of "why is this link duplicated" bugs.

Frontend pages. Frontend controllers extend the Titan frontend base and render through the package layout (@extends('titan::layouts.default') or the published equivalent). Put site-wide data (settings, menus, footer content) in a view composer or a base controller's share() call rather than in every action.

Settings pattern. Store editable site settings (site name, contact email, social links) as key/value rows with an admin settings screen, and expose them via a cached helper (setting('site.email')). Wrap the cache in a saved model event so edits invalidate immediately.

Permissions. Titan ships role/permission plumbing tied to the admin user model. Gate your custom modules with the package's permission middleware rather than ad-hoc if ($user->is_admin) checks, so the admin UI's permission screen stays truthful.

Uploads. Point the upload path config at storage/app/public and make sure php artisan storage:link has been run. Keep image variant definitions (thumb/medium/full) in one place — config or a model constant — because the admin listing, the edit preview, and the frontend template all read them.

Gotchas and Tips

The 2020 release date is the headline risk. Last release July 2020 means the package targets Laravel 6/7-era APIs. Composer will refuse to install it on Laravel 9/10/11 without --ignore-platform-reqs or a fork, and even then you'll hit removed helpers (str_slug, array_get, Route::namespace behavior changes, the $loginPath auth scaffolding). For a new project, budget for a fork or pick a maintained alternative; for a legacy app you're already running, pin your Laravel version explicitly.

Publishing is not idempotent. Running vendor:publish --force after an update overwrites your edited views and config. Diff before forcing; keep customizations in your own namespaced views that override via resources/views/vendor/titan/... and commit them.

Config cache hides your changes. php artisan config:cache during deploy will freeze config/titan.php. Any env-driven value inside it needs a matching env() call and a config:clear in your deploy script when debugging "my config change did nothing."

Migrations collide. The published migrations create users, roles, permissions, pages, and settings tables. If your app already has a users table, the Titan migration will fail or silently skip columns. Read every published migration file before running migrate, and disable the ones you don't need by moving them out of database/migrations.

Seeder credentials. The default admin user from the seeder is a known quantity. Change the password in the first five minutes; better, delete the seeded user and create your own via tinker, then remove the seeding step from your deploy pipeline.

Route and model naming collisions. Titan claims the /admin prefix and often generic model names (Page, Setting, Menu, User). If your domain needs a Page, either alias it (CmsPage) or configure the admin prefix away from anything you own. Check php artisan route:list after install — surprises here cause 404s that look like routing bugs but are silent overrides.

Asset order matters. The admin UI depends on a specific JS stack (jQuery, a datatables/grid plugin, bootstrap). Publishing assets into public/vendor/titan and then adding your own scripts after the layout's @stack('scripts') — not before — avoids "plugin is not a function" errors. If you swap the admin theme, expect to reimplement the grid's AJAX contract.

Debugging the admin base controller. When a CRUD screen 500s, the stack trace usually lands in the package's base controller, not yours. Add temporary logging around the $this->model resolution and the view-name resolution — a wrong protected $view or a model missing an expected trait/attribute is the usual culprit, and the error message points at the package rather than your class.

Extension points to prefer. Override Blade partials under resources/views/vendor/titan/, extend the base controllers, and use model events/observers for side effects. Avoid editing files under vendor/ — the next composer update erases them, and there will be no upstream fix given the release cadence.

Plan an exit ramp. Given maintenance risk, isolate Titan behind your own thin abstraction where feasible: your own AdminController extending Titan's, your own settings helper wrapping the package's, your own upload service. If you ever migrate to Filament/Nova/a bespoke panel, you change the abstraction layer instead of every controller.