From 4c5eae1b80205ba5ea96e4f7f9be1b30b834465a Mon Sep 17 00:00:00 2001 From: Otavio G Date: Fri, 21 Jun 2024 14:53:22 -0300 Subject: [PATCH] docs: edit README.md --- README.md | 322 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 277 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 1a4c26b..181c711 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,298 @@ -

Laravel Logo

+# Discord Clone -

-Build Status -Total Downloads -Latest Stable Version -License -

+## Table of Contents -## About Laravel +- [Introduction](#introduction) +- [Stack](#stack) +- [Installation](#installation) +- [Tests](#tests) +- [Documentation](#documentation) +- [First time in the project](#first-time-in-the-project) +- [About implementation](#about-implementation) -Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as: +## Introduction -- [Simple, fast routing engine](https://laravel.com/docs/routing). -- [Powerful dependency injection container](https://laravel.com/docs/container). -- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage. -- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent). -- Database agnostic [schema migrations](https://laravel.com/docs/migrations). -- [Robust background job processing](https://laravel.com/docs/queues). -- [Real-time event broadcasting](https://laravel.com/docs/broadcasting). +This is a simple discord clone with real time chat, authentication and guilds (servers) with channels system. +The objetive of this project is show a websocket example with Laravel Reverb. +Also, demonstrate examples of how use Laravel Sanctum and application of the SOLID principles. -Laravel is accessible, powerful, and provides tools required for large, robust applications. +## Stack -## Learning Laravel +- [Laravel 11]() +- [Laravel Reverb](https://reverb.laravel.com/) +- [Vue](https://vuejs.org/) +- [PostgreSQL](https://www.postgresql.org/) +- [Docker](https://www.docker.com/) +- [Pest](https://pestphp.com/) -Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. +## Installation -You may also try the [Laravel Bootcamp](https://bootcamp.laravel.com), where you will be guided through building a modern Laravel application from scratch. +To execute this project, you need to have installed Docker in your machine. After that, follow the steps: -If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library. +1. Clone the repository -## Laravel Sponsors +``` +git clone https://github.com/otaaaviio/disc-laravel.git +``` -We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com). +2. In src folder, execute the bin for setup: -### Premium Partners +```bash +./bin/setup.sh +``` -- **[Vehikl](https://vehikl.com/)** -- **[Tighten Co.](https://tighten.co)** -- **[WebReinvent](https://webreinvent.com/)** -- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)** -- **[64 Robots](https://64robots.com)** -- **[Curotec](https://www.curotec.com/services/technologies/laravel/)** -- **[Cyber-Duck](https://cyber-duck.co.uk)** -- **[DevSquad](https://devsquad.com/hire-laravel-developers)** -- **[Jump24](https://jump24.co.uk)** -- **[Redberry](https://redberry.international/laravel/)** -- **[Active Logic](https://activelogic.com)** -- **[byte5](https://byte5.de)** -- **[OP.GG](https://op.gg)** +3. Access in your browser the address: -## Contributing +``` +http://0.0.0.0:80 +``` -Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions). +For the next times, you can use this for stop or start the containers: -## Code of Conduct +```bash +./bin/start.sh +``` -In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct). +```bash +./bin/stop.sh +``` -## Security Vulnerabilities +## Tests -If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed. +This project contains units and integration tests. To execute the tests, you can use the command: -## License +```bash +./vendor/bin/sail test +``` -The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). +ps: You need run the containers before execute the tests. + +## First time in the project + +When you set up the project with setup.sh, will run seeder with 2 users:
+Adm user: + +``` +email: adm@admin.com +password: password +``` + +Normal user: + +``` +email: usr@user.com +password: password +``` + +With these credentials, you can access the application in different browsers and experience the real-time chat +functionality. + +## Documentation + +I use the [scramble](https://scramble.dedoc.co/) for the api documentation. You can see accessing the address: + +``` +http://0.0.0.0:80/docs/api +``` + +In this documentation, you can see the endpoints, request and response examples. + +## About implementation + +### Services:
+ +I use service abstraction, to separate the business logic from the controller and have a better maintenance.
+ +### Repositories:
+ +About repositories, I don't like use repository pattern in simple laravel projects, +because in majority cases, the eloquent is enough, and we don't change the framework project.
+In larger projects, where there might be a need to change the framework, the repository pattern is a good choice. + +### Websockets:
+ +I use Laravel Reverb to implement the websockets. It's not hard to implement, but debug this should be a little hard if +you don't have familiarity with websockets.
+Even though it's a relatively new technology, it's a good choice to learn and apply in your personal or professional +projects. + +### Jobs:
+ +I use jobs to send the mail to new users, with welcome message. And use a different connection to send the mail.
+ +### Tests:
+ +I use Pest for tests. It's a simple and clean test framework. I like it because it's easy to read and write tests.
+ +### Docker:
+ +I use the Laravel Sail with some modifications for this project, like change the images and add vite container.
+ +### FrontEnd:
+ +I use Vue for frontend, just for my familiarity with this framework. +And I focus in the backend, so the frontend is simple and functional. + +## Contributing and Examples + +You can fork this project and make a pull request with your changes. I will be happy to review and accept your +contribution. +If you follow the current project pattern, everything will work fine. :D +A example to you follow: + +Resource: + +```php +class ModelResource extends JsonResource +{ + public function toArray(Request $request): array + { + return [ + // here you can edit what you want to return + ]; + } +} +``` + +Request: + +```php +class ModelRequest extends FormRequest +{ + public function rules(): array + { + return [ + // some rules you want validated + ]; + } +} +``` + +Exceptions: + +```php +class ModelException extends Exception +{ + public function __construct($message = '', $code = StatusCode::HTTP_INTERNAL_SERVER_ERROR, ?Throwable $previous = null) + { + parent::__construct($message, $code, $previous); + } + + public static function someError(): self + { + return new self( + 'Some error message here', + StatusCode::HTTP_ERROR + ); + } + + public function render($request): JsonResponse + { + return response()->json([ + 'message' => $this->getMessage(), + ], $this->getCode()); + } +} +``` + +`Controller`: + +```php +public function store(ModelRequest $request) +{ + // this will clean fields that are not in the rules + $data = $this->validated(); + + //here you process the request, within show the business logic + $modelResource = $this->service->create($data); + + // here you can style the response and return + return response()->json([ + 'message' => 'Some message here', + 'model' => $modelResource + ], StatucCode::HTTP_CREATED); +} +``` + +Service: + +```php +public function create(array $data) +{ + // here you process the data and return the resource and treat errors with custom exceptions + + if($error) { + // this is useful to maintain the handling of errors in the same place + throw CustomException::someError(); + } + + return ModelResource::make($model); +} +``` + +Service: + +```php +// this functions should be implemented with interfaces to better maintenance and abstraction +public function store(EspecficRequest $request) +{ + // this will clean fields that are not in the rules + $data = $this->validated(); + + //here you process the request, within show the business logic + $modelResource = $this->service->create($data); + + // here you can style the response and return + return response()->json([ + 'message' => 'Some message here', + 'model' => $modelResource + ], StatucCode::HTTP_CREATED); +} +``` + +For Websockets, you can add new events to project, like: + +```php +class SomeEvent implements ShouldBroadcast +{ + use Dispatchable, InteractsWithSockets, SerializesModels; + + public function __construct( + public Model $model + ) { + // + } + + // channel where the event will be broadcast + public function broadcastOn(): Channel + { + return new Channel('channel.'.$this->model->id); + } + + // data to send in event + public function broadcastWith(): array + { + return [ + 'model' => $this->model + ]; + } + + // person event name to access in client side + public function broadcastAs(): string + { + return 'some-event'; + } +} +``` + +For more infos, you can see the [Laravel Documentation](https://laravel.com/docs) + +## Contact + +If you have any questions, you can contact me by email or linkedin: + +``` +oglamberty@inf.ufsm.br + +https://www.linkedin.com/in/otaaaviio/ +```