Speedy Laravel Package

Getting Started

• Check compatibility first. This package’s last release was in 2017, so treat it as a Laravel 5.x-era admin scaffold. Inspect composer.json in the repo for supported Laravel/PHP versions before installing. It is safest in a legacy Laravel app, a Dockerized legacy environment, or a throwaway admin prototype—not a new Laravel 10/11 project.
• Install and publish. Typical flow:

  composer require hanson/speedy
  php artisan vendor:publish --provider="Hanson\Speedy\SpeedyServiceProvider"
  php artisan migrate
  

  If the app is older than Laravel 5.5, register the service provider and aliases manually in config/app.php. Check the README for the exact provider namespace and publish tags.
• Create an admin user. Use the package’s install/seed command if provided, or seed a user directly. Then visit the configured admin route, usually /admin, and verify login.
• Where to look first:
  1. README.md for install commands and screenshots.
  2. config/speedy.php for route prefix, auth guard, middleware, upload paths, and menu settings.
  3. The package service provider and routes/ to understand registered routes and middleware.
  4. Migrations and seeders for required tables and default permissions.
  5. Example admin controllers/views for the intended CRUD pattern.
• First use case: build one small CRUD resource—e.g. Post—behind admin authentication. Create the model/migration, generate or write an admin controller, define list/form fields, add a menu entry, assign permissions, then test list/create/edit/delete and validation end to end.

Implementation Patterns

• One admin resource per model. Keep admin controllers separate from public controllers. Define grid/list columns, form fields, validation rules, and relationships in the admin controller. Use eager loading for relationship columns to avoid N+1 queries in lists.
• Standard CRUD workflow: migration/model → admin controller → menu item → permissions/roles → seed demo data → test as a non-super-admin user. This catches missing permissions and menu visibility issues early.
• Menu and permission configuration. If menus are database-backed, seed them rather than editing production data by hand. Pair menu entries with permission checks so operators only see what they can use. Keep role definitions in seeders so environments stay reproducible.
• Reuse Laravel conventions inside the admin. Use Form Requests or inline validation, database transactions for multi-table saves, policies/gates for authorization, and Eloquent scopes for filtered lists. The package provides the admin shell; your application should still own domain rules.
• Integrate with existing auth carefully. Decide whether the admin uses the default web guard or a separate admin guard. Keep middleware consistent across routes. If the app already has an admin area, mount Speedy under a distinct prefix to avoid route collisions.
• Custom pages and actions. For dashboards, reports, imports, or bulk actions, add custom admin routes/controllers rather than forcing everything through generated CRUD. Publish and override views when the default UI needs adjustment.
• File uploads and exports. Centralize upload paths in config, validate MIME type/size, and store outside the public root where possible. For exports/imports, queue long-running jobs and keep admin requests fast.
• Environment discipline. Use seeded demo data locally, but keep production migrations and permission seeders explicit. Cache config/routes only after verifying the package works uncached.

Gotchas and Tips

• Maintenance risk is the biggest gotcha. A 2017 admin package may rely on deprecated PHP behavior, old Laravel APIs, and abandoned frontend assets. Pin Composer versions, avoid blind framework upgrades, and isolate the admin code so it can be replaced later.
• Service provider auto-discovery may not work on older Laravel versions. If commands/routes are missing, register the provider manually and run php artisan route:list to confirm routes exist.
• Publishing tags and namespaces differ between versions. If vendor:publish does nothing, inspect the provider’s publishes() method or run php artisan vendor:publish interactively.
• Auth guard and middleware conflicts are common. Verify which guard the admin login uses, whether sessions/CSRF are configured, and whether route middleware matches the guard. Test login, logout, and permission denial separately.
• Migration order and existing schemas. Install into a clean database first, then compare generated tables against existing ones. Avoid running package migrations blindly in production; review them and make seeders idempotent.
• Cached config/routes can hide changes. After editing config or routes, run:

  php artisan config:clear
  php artisan route:clear
  php artisan view:clear
  

• Asset and storage issues. If styles/scripts 404, re-publish assets and check the public path. If uploads fail, check storage/ permissions and php.ini upload limits.
• Debugging approach: use route:list, Laravel logs, and temporary dd() in the admin controller to confirm which package layer handles the request. Inspect published views before editing vendor files.
• Extend through config, views, and custom controllers—not vendor edits. Vendor changes vanish on Composer updates. Prefer published overrides, custom fields, custom menu items, and dedicated middleware.
• Security hygiene: change default credentials immediately, enforce authorization on every custom admin route, validate uploads, and avoid exposing admin routes publicly without rate limiting or IP restrictions where appropriate.