It's recommended to use Docker to set up the development environment, so you don't need PHP or Composer on your system. Run this for the first-time setup:

docker run --rm \
    -v $(pwd):/var/www/html \
    -w /var/www/html \
    laravelsail/php84-composer:latest \
    bash -c "composer install --ignore-platform-reqs && php artisan sail:install --with=pgsql"

From this point onward, run all shell commands with the ./vendor/bin/sail prefix so they get run inside the container. You might want to set up a shell alias in ~/.bashrc to remove the relative path:

alias sail='./vendor/bin/sail '

Then, it's just one command every time you want to spin up your development environment:

sail up -d

1b. Manual

Alternatively, you can install PHP 8 (with the relevant extensions), PHP Composer, and Postgres on your system, then go into this directory and run:

composer install

Don't use the sail prefix if you install it this way.

2. Migrations

Apply all migrations to the database:

sail php artisan migrate

Note: this step has to be redone every time a new database migration is written.

3. Generate key

Generate the application encryption key:

sail php artisan key:generate

Development

Dev Server

Start the Laravel dev server with this command:

sail php artisan serve

Then you can go to http://localhost/ in your browser (if using Sail) or http://localhost:8000/ (for manual installs). The site will live update any time you make changes.

Create Model

sail php artisan make:model

Check out the flags you can pass into this command first, since it can save you from writing boilerplate (controllers, factories, migrations, tests, etc).

PHP Console

sail php artisan tinker

Really useful for doing database operations and such by interacting with model objects (no SQL required).

Rebuilding Sail Containers

Only do this if you totally break something in the container or need a fresh start after changing something in compose.yaml. It may take a while.

sail build --no-cache

For troubleshooting purposes, note that the containers still can access real paths on your system (like PHP packages going in ./vendor, Postgres databases in the sail-pgsql volume), so you may want to try clearing those first.

Testing

You should install an HTTP request client like Insomnia. Make sure you are setting the Accept: application/json and Referer: localhost headers in all requests (the Insomnia project already does this) -- this application is not designed to generate any HTML views, aside from email messages and the password reset page.

List all Routes

sail php artisan route:list

Authenticating

Authentication is handled by Laravel Sanctum and Laravel Fortify. Instead of using JWTs or non-expiring API tokens, which come with a host of security issues, we use good old fashioned cookies to maintain the logged-in user's session.

Sanctum Routes

GET /sanctum/csrf-cookie: must be ran first to get the XSRF-TOKEN cookie. Then, the client is responsible for pasting this token into the X-XSRF-TOKEN request header of all subsequent authenticated requests. Make sure to URL-decode it first (basically, if there's a %3D at the end, change it to =). The Insomnia project takes care of this for you, as long as you hit run in the first place.

Fortify Routes

POST /login

POST /register

POST /logout

Application Routes

GET /api/user

Listings Resource

A group of resource routes created by Laravel for standard CRUD operations.

GET /api/listing

POST /api/listing

GET /api/listing/{listing}

PUT/PATCH /api/listing/{listing}

DELETE /api/listing/{listing}

Verifying your Email

New accounts need to have their emails marked as verified in order to post on the site. For testing purposes, you don't need to send an actual email, you can just update the database:

sail php artisan serve
> $u = User::find(1);
> $u->email_verified_at = now();
> $u->save();