1 # ![Laravel Example App](logo.

png)
2
3 [![Build
Status](https://img.shields.io/travis/gothinkster/laravel-realworld-example-app/master
.svg)](https://travis-ci.org/gothinkster/laravel-realworld-example-app)
[](https://gitt
er.im/realworld-dev/laravel) [![GitHub
stars](https://img.shields.io/github/stars/gothinkster/laravel-realworld-example-app.s
vg)](https://github.com/gothinkster/laravel-realworld-example-app/stargazers)
[![GitHub
license](https://img.shields.io/github/license/gothinkster/laravel-realworld-example-a
pp.svg)](https://raw.githubusercontent.com/gothinkster/laravel-realworld-example-app/m
aster/LICENSE)
4
5 > ### Example Laravel codebase containing real world examples (CRUD, auth, advanced
patterns and more) that adheres to the
[RealWorld](https://github.com/gothinkster/realworld-example-apps) spec and API.
6
7 This repo is functionality complete — PRs and issues welcome!
8
9 ----------
10
11 # Getting started
12
13 ## Installation
14
15 Please check the official laravel installation guide for server requirements before
you start. [Official
Documentation](https://laravel.com/docs/5.4/installation#installation)
16
17 Alternative installation is possible without local dependencies relying on
[Docker](#docker).
18
19 Clone the repository
20
21 git clone [email protected]:gothinkster/laravel-realworld-example-app.git
22
23 Switch to the repo folder
24
25 cd laravel-realworld-example-app
26
27 Install all the dependencies using composer
28
29 composer install
30
31 Copy the example env file and make the required configuration changes in the .env file
32
33 cp .env.example .env
34
35 Generate a new application key
36
37 php artisan key:generate
38
39 Generate a new JWT authentication secret key
40
41 php artisan jwt:generate
42
43 Run the database migrations (**Set the database connection in .env before migrating**)
44
45 php artisan migrate
46
47 Start the local development server
48
49 php artisan serve
50
51 You can now access the server at http://localhost:8000
52
53 **TL;DR command list**
54
55 git clone [email protected]:gothinkster/laravel-realworld-example-app.git
56 cd laravel-realworld-example-app
57 composer install
58 cp .env.example .env
 59 php artisan key:generate
60 php artisan jwt:generate
61
62 **Make sure you set the correct database connection information before running the
migrations** [Environment variables](#environment-variables)
63
64 php artisan migrate
65 php artisan serve
66
67 ## Database seeding
68
69 **Populate the database with seed data with relationships which includes users,
articles, comments, tags, favorites and follows. This can help you to quickly start
testing the api or couple a frontend and start using it with ready content.**
70
71 Open the DummyDataSeeder and set the property values as per your requirement
72
73 database/seeds/DummyDataSeeder.php
74
75 Run the database seeder and you're done
76
77 php artisan db:seed
78
79 ***Note*** : It's recommended to have a clean database before seeding. You can
refresh your migrations at any point to clean the database by running the following
command
80
81 php artisan migrate:refresh
82
83 ## Docker
84
85 To install with [Docker](https://www.docker.com), run following commands:
86
87 ```
88 git clone [email protected]:gothinkster/laravel-realworld-example-app.git
89 cd laravel-realworld-example-app
90 cp .env.example.docker .env
91 docker run -v $(pwd):/app composer install
92 cd ./docker
93 docker-compose up -d
94 docker-compose exec php php artisan key:generate
95 docker-compose exec php php artisan jwt:generate
96 docker-compose exec php php artisan migrate
97 docker-compose exec php php artisan db:seed
98 docker-compose exec php php artisan serve --host=0.0.0.0
99 ```
100
101 The api can be accessed at [http://localhost:8000/api](http://localhost:8000/api).
102
103 ## API Specification
104
105 This application adheres to the api specifications set by the
[Thinkster](https://github.com/gothinkster) team. This helps mix and match any
backend with any other frontend without conflicts.
106
107 > [Full API Spec](https://github.com/gothinkster/realworld/tree/master/api)
108
109 More information regarding the project can be found here
https://github.com/gothinkster/realworld
110
111 ----------
112
113 # Code overview
114
115 ## Dependencies
116
117 - [jwt-auth](https://github.com/tymondesigns/jwt-auth) - For authentication using
JSON Web Tokens
118 - [laravel-cors](https://github.com/barryvdh/laravel-cors) - For handling
Cross-Origin Resource Sharing (CORS)
119
120 ## Folders
121
122 - `app` - Contains all the Eloquent models
123 - `app/Http/Controllers/Api` - Contains all the api controllers
124 - `app/Http/Middleware` - Contains the JWT auth middleware
125 - `app/Http/Requests/Api` - Contains all the api form requests
126 - `app/RealWorld/Favorite` - Contains the files implementing the favorite feature
127 - `app/RealWorld/Filters` - Contains the query filters used for filtering api requests
128 - `app/RealWorld/Follow` - Contains the files implementing the follow feature
129 - `app/RealWorld/Paginate` - Contains the pagination class used to paginate the result
130 - `app/RealWorld/Slug` - Contains the files implementing slugs to articles
131 - `app/RealWorld/Transformers` - Contains all the data transformers
132 - `config` - Contains all the application configuration files
133 - `database/factories` - Contains the model factory for all the models
134 - `database/migrations` - Contains all the database migrations
135 - `database/seeds` - Contains the database seeder
136 - `routes` - Contains all the api routes defined in api.php file
137 - `tests` - Contains all the application tests
138 - `tests/Feature/Api` - Contains all the api tests
139
140 ## Environment variables
141
142 - `.env` - Environment variables can be set in this file
143
144 ***Note*** : You can quickly set the database information and other variables in this
file and have the application fully working.
145
146 ----------
147
148 # Testing API
149
150 Run the laravel development server
151
152 php artisan serve
153
154 The api can now be accessed at
155
156 http://localhost:8000/api
157
158 Request headers
159
160 | **Required** | **Key** | **Value** |
161 |---------- |------------------ |------------------ |
162 | Yes | Content-Type | application/json |
163 | Yes | X-Requested-With | XMLHttpRequest |
164 | Optional | Authorization | Token {JWT} |
165
166 Refer the [api specification](#api-specification) for more info.
167
168 ----------
169
170 # Authentication
171
172 This applications uses JSON Web Token (JWT) to handle authentication. The token is
passed with each request using the `Authorization` header with `Token` scheme. The
JWT authentication middleware handles the validation and authentication of the token.
Please check the following sources to learn more about JWT.
173
174 - https://jwt.io/introduction/
175 - https://self-issued.info/docs/draft-ietf-oauth-json-web-token.html
176
177 ----------
178
179 # Cross-Origin Resource Sharing (CORS)
180
181 This applications has CORS enabled by default on all API endpoints. The default
configuration allows requests from `http://localhost:3000` and
`http://localhost:4200` to help speed up your frontend testing. The CORS allowed
origins can be changed by setting them in the config file. Please check the following
sources to learn more about CORS.
182
183 - https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
184 - https://en.wikipedia.org/wiki/Cross-origin_resource_sharing
185 - https://www.w3.org/TR/cors