Laravel5 Angular Material Starter Laravel Package

Getting Started

This is a starter kit, not a library you require — you bootstrap a whole app from it.

composer create-project jadjoubran/laravel5-angular-material-starter myapp
# or: git clone … && composer install
cd myapp
cp .env.example .env
php artisan key:generate
php artisan jwt:secret          # JWT_SECRET is required as of 3.x — auth is wired out of the box
# edit .env: DB_*, APP_URL, MAIL_* (forgot-password needs a working mailer)
php artisan migrate --seed
npm install && bower install
gulp            # or `gulp watch` during development
php artisan serve

First things to open, in this order:

1. app/Http/routes.php — the /api/* surface (including the sample JWT-protected routes added in 3.2.0) plus the catch‑all {any?} route that hands off to Angular.
2. app/Http/Controllers/Auth/AuthController.php — login/register/logout/forgot-password/reset returning JWTs.
3. public/js/app.js — Angular module, $authProvider (Satellizer) config, $stateProvider, and the registered HTTP interceptors.
4. public/js/controllers/, public/js/services/, public/js/directives/ — each with a matching *.spec.js as of 3.2.0.
5. gulpfile.js — Elixir task wiring for Sass/JS/partials, plus the Karma test task.

First use case: register a user at /register, log in at /login, inspect the returned JWT, then call a protected endpoint (GET /api/me or the sample authenticated routes) with Authorization: Bearer <token> from Postman before touching Angular. Then run the test suite once (karma start or the gulp test task) so you know the green baseline you're expected to keep.

Implementation Patterns

Generate, don't hand-wire (3.2.0). The kit now ships artisan generators — ng:directive for the cases directives are actually needed, plus the controller/service generators. They auto-import the new file into the relevant index.*.js barrel and auto-generate a matching spec. Use them; they are the intended day-to-day entry point:

php artisan ng:directive myHighlight
# creates public/js/directives/myHighlight.directive.js
# creates public/js/directives/myHighlight.directive.spec.js
# appends the import to public/js/directives/index.js

Adding an API resource end‑to‑end. The kit's whole workflow is one vertical slice:

1. Route in app/Http/routes.php inside the Route::group(['prefix' => 'api', 'middleware' => 'jwt.auth'], …) block (leave auth endpoints outside it). The sample JWT-authenticated routes from 3.2.0 are your copy-paste template.
2. Controller returns response()->json(...) — no Blade, the frontend never sees HTML.
3. Generate the Angular service with the generator; wrap $http.get/post. You no longer read localStorage yourself — Satellizer's $auth interceptor attaches the token.
4. Generate the controller and a partial in public/views/, register the state in $stateProvider (route files are now consistently named *.routes.js — follow that convention or the build/barrel won't pick it up).
5. Run gulp so the new JS is concatenated, then karma start to run the generated spec.

JWT flow pattern (now out of the box). Login POSTs to /api/authenticate, receives { token }; call $auth.setToken(token) — Satellizer's interceptor adds Authorization: Bearer … to every subsequent request, so delete any hand-rolled $http auth interceptor you wrote against an older version, or you'll double-send the header. Backend protection is jwt.auth middleware; frontend protection is a resolve on the state (or $stateChangeStart). Keep the two in sync — the backend is authoritative.

Forgot password. New in 3.2.0 and JWT-native: a request endpoint emails a reset link carrying a token, and the reset endpoint accepts the new password plus that token. You must configure MAIL_* in .env and point the link at your SPA route; check config/jwt.php ttl — a short TTL means reset links expire faster than users expect.

Error handling. The interceptor now surfaces errors other than 422 (previously validation failures only). Use the registered warn theme for $mdToast on generic failures and keep 422 mapped to field-level ng-messages. Don't stack a second generic toast on top of the 422 branch — the interceptor already fires.

Angular Material dialogs. Templates are now *.dialog.html (renamed in 3.2.0). Use md-input-container + ng-messages for validation, submit through the service, and show $mdToast/$mdDialog on success/failure. The kit's login/register views are your template.

Eloquent → Angular. Prefer plain toArray() or a transformer for payloads; the Angular side expects flat JSON. Keep relationships explicit (with('comments')) — no lazy loading through the API.

Testing with ngDescribe. Write specs as describeComponent/describeService blocks so DI mocking stays consistent with the generated ones; karma start in watch mode alongside gulp watch is the practical dev loop.

Gotchas and Tips

Everything here is end‑of‑life. AngularJS (1.x) went EOL Dec 2021, Laravel 5.x is unsupported, tymon/jwt-auth at the pinned version has known CVEs. Treat this repo as a reference architecture, not a production base — port the patterns to a current stack rather than shipping it. The 3.2.0 polish doesn't change this.

Generators rewrite your barrels. Auto-import edits index.js / index.routes.js files directly, so two branches adding components in parallel will conflict there, and re-running a generator can append a duplicate import. On a conflict, resolve by hand and eyeball the file — don't just take "ours" or "theirs".

Renamed template suffixes break older forks. *.dialog.html replaced the previous dialog naming in 3.2.0. Any custom directive or $mdDialog.show({ templateUrl: … }) pointing at the old path silently 404s (the dialog just doesn't open — no console error worth reading). Grep your templates after upgrading.

Satellizer now owns the token — don't double-interceptor. If you're upgrading from an older checkout that shipped a hand-written $http request interceptor, remove it. Two interceptors means duplicated Authorization headers and confusing 401s on some proxies.

Node/Gulp toolchain breaks on modern Node. Gulp 3 requires Node ≤ 10–11 (nvm install 10 && nvm use 10). The new Karma task has the same constraint — Karma/PhantomJS-era tooling is equally unhappy on Node 18+. Bower is deprecated; if bower install fails, npm install -g bower or migrate that dependency to npm manually.

APP_KEY and JWT secret are coupled. Rotating .env APP_KEY after seeding invalidates stored tokens (and encrypted sessions). If everyone is suddenly 401'd, this is usually why — clear the Satellizer token and re‑login.

CORS bites before Angular does. Enable barryvdh/laravel-cors and make sure Authorization is in allowedHeaders — otherwise the preflight passes but the real request 401s, which is easy to misread in DevTools.

The catch‑all route must exclude /api. A greedy Route::get('{any?}', …) swallows API calls and returns the Angular shell instead of JSON. Check route ordering first when an endpoint "returns HTML".

Debugging recipe: DevTools → Network → inspect the request headers; paste the token into jwt.io to see exp/claims; storage/logs/laravel.log for backend exceptions; php artisan route:list to confirm registration; karma start --single-run to see which generated spec broke. For token‑expiry issues, look at config/jwt.php (ttl, refresh_ttl) — there is still no auto‑refresh; add a refresh endpoint yourself.

Build artifacts are not committed. .gitignore excludes public/build, public/css/app.css, node_modules, bower_components. Your deploy pipeline must run npm install && bower install && gulp --production — forgetting this ships a broken frontend. Tests are not in the deploy path; wire karma start --single-run into CI separately.

Extension points worth keeping: the Satellizer $authProvider config + error interceptor, the $stateProvider/index.routes.js block (one place to register pages), and the api route group (one place to add middleware). If you fork the project, those three files are where 80% of your day‑to‑day edits will land.