127 lines
3.7 KiB
Markdown
127 lines
3.7 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: http://localhost` headers in all requests -- this application is not designed to generate any HTML views, aside from email messages and the password reset page. (The Insomnia project already does this.)
|
|
|
|
### 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`
|