153 lines
4.3 KiB
Markdown
153 lines
4.3 KiB
Markdown
# E-Waste Backend
|
|
|
|
## Installation
|
|
|
|
Clone the repo, and copy the `.env.example` file to `.env`.
|
|
|
|
### 1a. Laravel Sail / Docker (Recommended)
|
|
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
alias sail='./vendor/bin/sail '
|
|
```
|
|
|
|
Then, it's just one command every time you want to spin up your development environment:
|
|
|
|
```bash
|
|
sail up -d
|
|
```
|
|
|
|
### 1b. Manual
|
|
|
|
Alternatively, you can install PHP 8 (with the [relevant extensions](https://stackoverflow.com/questions/40815984/how-to-install-all-required-php-extensions-for-laravel)), PHP Composer, and Postgres on your system, then go into this directory and run:
|
|
|
|
```bash
|
|
composer install
|
|
```
|
|
|
|
Don't use the `sail` prefix if you install it this way.
|
|
|
|
### 2. Migrations
|
|
|
|
Apply all migrations to the database:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sail php artisan key:generate
|
|
```
|
|
|
|
## Development
|
|
|
|
|
|
### Dev Server
|
|
|
|
Start the Laravel dev server with this command:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](https://laravel.com/docs/12.x/controllers#resource-controllers) 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:
|
|
|
|
```bash
|
|
sail php artisan serve
|
|
> $u = User::find(1);
|
|
> $u->email_verified_at = now();
|
|
> $u->save();
|
|
```
|