Starter Framework Laravel Package

Getting Started

• Treat this as a Laravel 5.x-era application skeleton, not a modern library. First verify PHP/Composer compatibility: expect PHP 7.1–7.4 and MySQL. Pin your platform before installing:

  "config": {
    "platform": { "php": "7.4.33" }
  }
  

• Create or clone a project, then install:

  composer create-project someline/starter-framework myapp
  # or clone the repo and run:
  composer install
  cp .env.example .env
  php artisan key:generate
  

• Configure .env early: APP_URL, database, mail, cache/session drivers, filesystem disks, and JWT settings. If JWT is used, set JWT_SECRET (php artisan jwt:secret if the command exists in the installed version).
• Run the baseline:

  php artisan migrate --seed
  php artisan storage:link
  php artisan route:list
  

  Check seeders for roles/permissions/users; many starter kits ship default admin credentials.
• Look first at:
  • routes/api.php and routes/web.php
  • app/Http/Controllers/Api/
  • app/Models/ and app/Repositories/ if present
  • app/Transformers/ if present
  • config/auth.php, config/jwt.php, config/entrust.php
  • vendor/someline/foundation/ for base model/controller/repository/transformer behavior
  • vendor/someline/image/ if image handling is included
• First use case: expose a small authenticated CRUD API. Copy an existing API controller/model/transformer trio, create a migration and model for a simple resource such as Post, add a versioned route under the API middleware group, then test login, token use, listing, creation, update, and deletion with curl or Postman.

Implementation Patterns

• Follow the existing base-class layering. In a typical Someline Starter install, models extend Someline\Foundation\BaseModel, controllers extend BaseController, repositories extend BaseRepository, and transformers extend BaseTransformer. Keep new code consistent instead of introducing a second architecture.
• Thin controllers, repository-backed queries, transformer output. Put filtering/pagination in repositories and response shaping in transformers. This keeps API responses consistent and avoids leaking Eloquent models directly.

  // app/Http/Controllers/Api/V1/PostController.php
  public function index(PostRepository $posts)
  {
      return $this->response->paginator(
          $posts->paginate(request()->all()),
          new PostTransformer()
      );
  }
  

  Confirm the exact response helper in vendor/someline/foundation; adapt to the installed version.
• Use the package’s auth stack deliberately. If JWT is present, login issues a token, API routes use the JWT middleware, and clients send Authorization: Bearer <token>. Keep login/refresh/me endpoints separate from resource endpoints.
• Use Entrust roles/permissions as coarse-grained gates. Seed roles and permissions, attach them to users, and protect routes with role/permission middleware. For fine-grained “owns this record” checks, add policies or explicit controller checks rather than overloading Entrust.
• Version the API from day one. Keep routes under /api/v1/... even for a small app. It makes later auth or response changes less painful.
• Use FormRequests for validation. Keep validation out of controllers so the same rules can be reused by API and web entry points.
• Handle image/file uploads through the bundled image layer if present. Use the package’s upload facade/model rather than writing a parallel uploader; store metadata consistently and return public URLs through transformers. Confirm disk paths and storage:link before debugging frontend 404s.
• Standardize API errors. Extend the exception handler to return JSON for API requests and preserve the package’s existing error envelope. This matters more than adding new endpoints.
• Day-to-day workflow: copy the nearest existing module, rename model/repository/transformer/controller, add migration, add route, add permission seeder, then write one feature test covering auth plus CRUD. Use php artisan route:list, php artisan migrate:status, and storage/logs/laravel.log as the first debugging loop.
• Frontend integration: configure CORS for the frontend origin, store JWTs carefully, and add an interceptor that refreshes or logs out on 401. Do not mix session auth and bearer-token auth on the same API group without a clear reason.

Gotchas and Tips

• This is legacy software. Last release was 2019 and the score/stars are low. Expect Laravel 5.x constraints, abandoned dependencies, and PHP 8 incompatibility. Freeze Composer dependencies, pin PHP 7.4 in CI/local Docker, and avoid exposing it to the public internet without a security review. Plan an extraction/migration path rather than building a long-lived product directly on it.
• Composer resolution will fight you. Newer packages will demand Laravel 8+ or PHP 8. Use composer why-not laravel/framework and prefer pinned older versions. Avoid --ignore-platform-reqs unless you understand the runtime mismatch.
• JWT misconfiguration is the most common auth failure. Missing JWT_SECRET, stale config cache, wrong middleware alias, expired tokens, and blacklist/refresh settings all produce confusing 401s. Run php artisan config:clear after .env changes and inspect config/jwt.php.
• Entrust caches permissions. After changing roles/permissions in seeders or tinker, clear the application cache and any Entrust cache. Confirm middleware aliases are registered in app/Http/Kernel.php.
• Base classes hide behavior. Mass assignment, pagination defaults, response envelopes, and route model binding may live in vendor/someline/foundation. Read the vendor source before overriding methods; otherwise you can silently break API contracts.
• Migration and seeder order matters. Entrust/JWT/image packages may publish their own migrations. Run vendor publishes before app migrations, and check whether seeders assume existing roles or users.
• Filesystem issues look like application bugs. Image 404s usually mean missing storage:link, wrong FILESYSTEM_DRIVER, permissions on storage/ and bootstrap/cache, or a transformer returning a relative path. Verify with php artisan storage:link and a direct URL.
• Route/auth mismatch: auth:api and jwt.auth are not interchangeable. Pick the package’s intended middleware for API routes and test with a real token, not only php artisan tinker.
• Debugging sequence: route:list → config:clear → check middleware group → inspect storage/logs/laravel.log → reproduce with curl → add a feature test. For CORS/preflight issues, test OPTIONS separately from GET.
• Extension points worth using: replace JWT middleware with Laravel Sanctum/Passport if you modernize auth; replace Entrust checks with Laravel Gates/Policies; keep transformers/repositories as the seam if you later move domain code into a newer Laravel app. The safest long-term move is to treat Someline Starter as a reference implementation and migrate business logic incrementally.