https://github.com/fecony/theam_crm
Laravel API to manage CRM customers
https://github.com/fecony/theam_crm
Last synced: about 2 months ago
JSON representation
Laravel API to manage CRM customers
- Host: GitHub
- URL: https://github.com/fecony/theam_crm
- Owner: fecony
- Created: 2021-05-27T06:14:01.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-06-16T12:25:48.000Z (almost 4 years ago)
- Last Synced: 2025-02-15T04:27:40.694Z (3 months ago)
- Language: PHP
- Homepage: https://fecony.github.io/theam_crm/
- Size: 642 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# THEAM CRM API Service
CRM API Service used to manage customers.
## Getting Started
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
### Prerequisites
Things you will need:
- [PHP](https://www.php.net/downloads.php)
- [Composer](https://getcomposer.org/download/)
- [Docker](https://docs.docker.com/get-docker/) (not required)
- [Valet](https://laravel.com/docs/8.x/valet) (not required)
- [Valet +](https://github.com/weprovide/valet-plus)
Things you might need to test API:
- [Postman](https://www.postman.com/downloads/)
- [Insomnia](https://insomnia.rest/download)
Or you can use [hoppscotch](https://hoppscotch.io/)!
#### If you are not going to use Docker make sure you have all required PHP extensions installed on your local machine https://laravel.com/docs/8.x/deployment#server-requirements
## Environment Variables
To run this project, you will need to add the following environment variables to your `.env` file
`GITHUB_CLIENT_ID`
`GITHUB_CLIENT_SECRET`
#### To get those values you have to create github OAuth application. Folow [Github docs](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) to create OAuth application.
For authorization callback use your local app url if you are running app locally using Valet / Valet +.
Or if you are running app in Docker or using built-in server.
## Installation
Clone the project
```bash
git clone [email protected]:Fecony/theam_crm.git
```
Go to the project directory
```bash
cd theam_crm
```
Install dependencies
#### Docker π³
> This command will run Docker container to install application dependencies
> You can refer to Laravel Sail [docs](https://laravel.com/docs/8.x/sail#installing-composer-dependencies-for-existing-projects) for other useful commands!
```bash
docker run --rm \
-u "$(id -u):$(id -g)" \
-v $(pwd):/opt \
-w /opt \
laravelsail/php80-composer:latest \
composer install --ignore-platform-reqs
```
#### Valet / Valet + / Laravel server
```bash
composer install
```
Copy .env.example file to .env on the root folder.
```bash
cp .env.example .env
```
## Run Locally
Run `php artisan key:generate` to generate app key.
Run `php artisan storage:link` to create the symbolic link.
> If you are running Docker, you can use the same commands but swap `php` to `sail`.
#### Docker π³
By default application is configured to run in Docker container. You don't have to change any environment configuration setting.
To run app in Docker container make sure that Docker is running.
Then run Laravel Sail command to run Docker in background:
```bash
./vendor/bin/sail up -d
```
After you application is running in Docker container run `sail artisan migrate` to run migration files.
### Running application locally without Docker
To run application locally you have to change your `.env` file mysql settings. Change following settings to match youΠΊ local mysql settings:
```bash
DB_HOST=127.0.0.1
DB_PORT=3306
# Change this settings to match you database name and mysql user
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password
```
Then run `php artisan migrate` to run migration files.
#### Valet / Valet +
Valet is a Laravel development environment for macOS minimalists. You can use it to run Laravel application locally.
Read more about Valet here: https://laravel.com/docs/8.x/valet
Also you can use [Valet plus](https://github.com/weprovide/valet-plus) that is more powerful version of Laravel Valet.
Follow Valet docs to park and link you application. After that you will be able to access it by visiting
#### Laravel built-in server
To run application using Laravel built in server run following artisan command:
```bash
php artisan serve
```
Then you can access you app running on
## Authorization flow β¨
In order to access protected API endpoints you have to authenticate user by using "Github Authentication" - `api/v1/auth/github` endpoint.
You will get url that user has to visit in order to give us access to his Github Account. After successful authentication user will be redirected and you will receive user basic information with token that you have to use for authorization.
> Example response:
```
"user": {
"id": 1,
"email": "[email protected]",
"username": "Github username",
"is_admin": false
},
"token": "BEARER TOKEN"
```
### Admin user
In order to access admin protected API endpoints you have to toggle your test user admin status.
You can to so by updating database value for user. Or you can use `admin:toggle` artisan command that will be available in `local` mode
You can run artisan command to toggle admin state for provided user:
```bash
// on your local machine.
php artisan admin:toggle {username}
// Docker π³
sail artisan admin:toggle {username}
```
#### To authenticate requests, include an Authorization header with the value "Bearer {BEARER TOKEN}".
## Running Tests
Tests are running in sqlite database. You can download it [here](https://www.sqlite.org/download.html)
To run tests you have to create `.env.testing` file:
```bash
cp .env .env.testing
```
set following environment variables:
```bash
APP_ENV=testing
DB_CONNECTION=sqlite
DB_HOST=null
DB_PORT=null
DB_DATABASE=:memory:
DB_USERNAME=null
DB_PASSWORD=null
GITHUB_CLIENT_ID=test
GITHUB_CLIENT_SECRET=test
```
Then you can run `composer test` command to run tests using PHPUnit.
Or you can run `php artisan test` to see fancy output β¨
If everything is fine you will see happy tests output π§ͺ
#### Docker π³
After starting Docker container by running `./vendor/bin/sail up -d` you can run `sail test` to run tests.
## Documentation
You can view deployed version of docs at [Github Pages](https://fecony.github.io/theam_crm/)
To regenerate docs run:
```bash
php artisan scribe:generate
```
Also you can find Postman collection by visiting /docs.postman.
## Troubleshooting - Common Problems
This page lists solutions to problems you might encounter. Here is a list of common problems.
### Access denied for user '[email protected]'... | Docker π³
- Try to run `./vendor/bin/sail down --rmi all -v`. It will remove all images used by any service and remove named volumes.
- (optional) You might run `./vendor/bin/sail build --no-cache` to build image before running next command
- Then run `./vendor/bin/sail up -d` again to build container.
### Issues with photo saving / photo seeder | Storage folder permission issue
Usually it happens when you have wrong permission set on storage folder.
- But there are no exact steps to fix this problem yet :(
### Cannot start service mysql: Ports are not available: listen tcp 0.0.0.0:3306: bind: address already in use
Most likely you have running mysql service locally. There are 2 solutions to this isuse:
- You have to stop your local mysql service to make port 3306 available for docker
- Use `FORWARD_DB_PORT` in your .env to use different port for docker port binding
- `FORWARD_DB_PORT=3307`
## Authors
- [@fecony](https://www.github.com/fecony)
## Acknowledgements
- Thanks to Taylor Otwell for creating Laravel β¨
- [Readme generator](https://readme.so/)
## Support
For support, contact me [@fecony](https://www.github.com/fecony).
## License
[MIT](https://choosealicense.com/licenses/mit/)