Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ragboyjr/laravel-api-skeleton

Laravel API Skeleton
https://github.com/ragboyjr/laravel-api-skeleton

Last synced: 26 days ago
JSON representation

Laravel API Skeleton

Awesome Lists containing this project

README 

        
# Laravel API Skeleton



Install via:



```

composer create-project ragboyjr/laravel-api-skeleton {name}

```



Once installed, you'll want to run the following:



```

mv .editor/project.sublime-project .editor/acme-svc.sublime-project

find . -type d \( -path ./vendor -o -path ./.git \) -prune -o -type f -print -exec sed -i '' -e 's/{project}/acme-svc/g' {} \;

find . -type d \( -path ./vendor -o -path ./.git \) -prune -o -type f -print -exec sed -i '' -e 's/{project_underscore}/acme_svc/g' {} \;

find . -type d \( -path ./vendor -o -path ./.git \) -prune -o -type f -print -exec sed -i '' -e 's/{project_title}/Acme Svc/g' {} \;

find . -type d \( -path ./vendor -o -path ./.git \) -prune -o -type f -print -exec sed -i '' -e 's/{project_doctrine_ns}/Acme/g' {} \;

find ./tests -type f -print -exec sed -i '' -e 's/namespace App\\/namespace Acme\\Svc\\/g' {} \;

./artisan app:name 'Acme\Svc'

make ignored-files

```



Once completed, start docker via `docker-compose up` and run `./artisan doctrine:migrations:diff` to generate the initial migration.



## Development Setup



1. copy over all the example files: `make ignored-files`

2. Start the docker containers: `docker-compose up`

3. Exec into the `{project}` container via `docker exec -it {project} bash`

4. Run `make setup` to initialize the repo. This will initialize all aspects of the repo, you can see what this script does by viewing the `Makefile`.



At the end of `make setup`, it should have generated a long access token, you'll need to copy that into the .env and set the `INTEGRATION_API_TOKEN` value.



To verify that you've been setup correctly, you need to run `make test` and then `make refresh-db test-integration`. These will run the entire test suite. If any fail, then there was an issue with setup that will need to be resolved.



## Development



This app is built with Laravel and Doctrine.



### Migrations



From inside of the `{project}` container, run `./artisan doctrine:migrations:migrate` to load the database. You'll need to run this every time there is a new migration. You should be in a habit to just run migrations when you pull the latest code from `stg`.



## Generating Migrations



The best way to manage migrations is by configuring the metadata yaml files first, then simply running `./artisan doctrine:migrations:diff`. This will create a migration file that will take the diff of your current local db to the migration mapping files. Keep this in mind because if you forgot to run `./artisan doctrine:migrations:migrate` to bring your local db up to the latest, running the migrations-diff command could re-apply some database changes which will **break the migrations.**



## Testing



Unit Testing



```

make test

```



Integration Testing



```

make test-integration

```



Make sure all tests pass before pushing up.



### Workflow



The easiest way to develop with phpunit and testing is to create specific tests for whatever you are doing, and then run them individually with phpunit.



For example, if I'm working on the `tests/Integration/RepApiTest` `testApproveRepNotFound` method, I'll run inside of the docker container the following command to test only that method:



```

./vendor/bin/phpunit tests/Integration/RepAPITest.php --filter=testApproveRepNotFound

```



### Playground



`playground.php` is a file that allows you to quickly prototype/test code in the current app. It's just a simple console command, but the file is ignored, so that you don't have to worry about comitting those temp changes.



You can run the playground via: `./artisan playground`.



## Trouble Shooting



Here are some common errors you can get when developing and here's how to fix them.



### Status 500 in Tests



When asserting a status code in an integration test, and you get a status 500, the easiest way to start debugging is to just check the storage/logs/laravel.log and find the exception that occurred.



### Exception: Unresolvable dependency resolving [Parameter #0 [  $entityName ]] in class Doctrine\ORM\Mapping\ClassMetadataInfo



This can occur when you create a Repository class for an entity, and then type hint for the specific repository class but don't register the repository class in a service provider. To resolve this issue, you need to register the repository in the module's service provider like this:



```

addEntityRepo($this->app, Rep::class);

```



The `addEntityRepo` expects the laravel app instance and the class name of the **entity** not the repository class.



You can see examples of register repositories in the service provider in the different modules in the `app/Model` folder.