Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 7de35d5

Browse files
Update README.md
1 parent 817b8a4 commit 7de35d5

File tree

1 file changed

+395
-2
lines changed

1 file changed

+395
-2
lines changed

‎README.md

Lines changed: 395 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,395 @@
1-
# everything-laravel
2-
everything Laravel <> my personal and professional guide as a software developer
1+
# Everything Laravel
2+
Disclaimer : this is not a full Laravel tutorial.
3+
Rather, this is a collection of my most encountered
4+
situations, solutions and approaches. I'm
5+
documenting it because it's really hard to
6+
memorize these things even if you do it
7+
every single day and when returning
8+
to Laravel after a long break.
9+
10+
TOC
11+
* [Initial Setup](#initial-setup)
12+
* [Server Installation](#server-installation)
13+
* [Cloning the Project](#cloning-the-project)
14+
* [.env Config](#env-config)
15+
* [Composer & Artisan](#composer--artisan)
16+
* [Installing & Running the Project](#installing--running-the-project)
17+
* [Ignore The Platform Flag](#ignore-the-platform-flag)
18+
* [Unit & Integration Testing](#unit--integration-testing)
19+
* [Database Testing](#database-testing)
20+
* [Why Unit Tests ?](#why-unit-tests-)
21+
* [Safely Deleting A Module](#safely-deleting-a-module)
22+
* [New Routes In Backend](#new-routes-in-backend)
23+
* [New Package Installation](#new-package-installation)
24+
* [Adding New Column/s To A Table](#adding-new-columns-to-a-table)
25+
* [Database Interaction](#database-interaction)
26+
* [Eloquent & Laravel Query Builder](#eloquent--laravel-query-builder)
27+
* [Joining Tables](#joining-tables)
28+
* [Surrogate Key or Natural Key](#surrogate-key-or-natural-key)
29+
* [Database Normalization & Denormalization](#database-normalization--denormalization)
30+
* [Deploying Laravel On Test / Production Servers](#deploying-laravel-on-test--production-servers)
31+
* [Amazon EC2](#amazon-ec2)
32+
* [WinSCP & PuTTY](#winscp--putty)
33+
* [Git Pull or Manual File Transfer](#git-pull-or-manual-file-transfer)
34+
* [Different ENVs](#different-envs)
35+
* [Continuously Run Laravel On Test / Prod Env](#continuously-run-laravel-on-test--prod-env)
36+
37+
38+
## Initial Setup
39+
### Server Installation
40+
41+
Laravel has its own server when you run
42+
43+
`php artisan serve`
44+
45+
but that's not complete particularly when
46+
you need a database like MySQL, so
47+
we need to install a development server.
48+
49+
On Windows OS for the local development environment,
50+
we need XAMPP. Go ahead and install it.
51+
52+
### Cloning the Project
53+
54+
Most common way is to `git clone`.
55+
56+
If private, once you have access to the repo,
57+
you can clone it. If public, just clone it.
58+
59+
And make sure that it is inside the `htdocs`
60+
folder of XAMPP.
61+
62+
Another option is to simply download the
63+
project from GitHub. But you don't
64+
get the history of the project.
65+
66+
### .env Config
67+
Create a new text file name
68+
`.env` inside the root of the project.
69+
70+
Ask the concerned person for the
71+
exact content of the `.env` file if this is private.
72+
73+
If public, mostly it's the `example.env`, so go ahead
74+
copy the content of it and paste it on the actual `.env`.
75+
76+
Ever wonder why we don't include `.env` on GitHub ?
77+
78+
Because it tends to be different on different
79+
machines and usually contains sensitive data, like
80+
the API token.
81+
82+
### Composer & Artisan
83+
Familiarity with the Composer and Artisan is needed.
84+
85+
`composer` - is a dependency management tool for PHP
86+
87+
`artisan` - this is the command line utility of Laravel
88+
89+
more on this here,
90+
91+
https://laravel.com/docs/10.x/installation
92+
93+
### Installing & Running the Project
94+
95+
After cloning a project,
96+
97+
1. `composer install`
98+
99+
2. `php artisan migrate:fresh --seed`
100+
101+
when it's API and you have implemented
102+
this
103+
104+
https://dev.to/grantholle/implementing-laravel-s-built-in-token-authentication-48cf
105+
106+
you need to run
107+
108+
3. `php artisan make:token`
109+
110+
copy paste the token on the frontend or any other
111+
service that will be needing it
112+
113+
then finally, the moment of truth,
114+
115+
4. `php artisan serve`
116+
117+
and there you have it, enjoy coding !
118+
119+
## Ignore The Platform Flag
120+
If you run the `composer install` command and you get an error,
121+
temporarily we can use `--ignore-platform-reqs` to bypass the error
122+
but it's not a good practice. You need to identify
123+
what is causing the error.
124+
125+
For example, when we use an external
126+
package QR Code, we need to enable GD Extension, hence
127+
edit `php.ini` and uncomment `extension=gd`. Then
128+
try `composer install` again.
129+
130+
This way we are installing the same versions
131+
of the required packages.
132+
133+
## Unit & Integration Testing
134+
135+
In modular approach, you need to tweak the default
136+
TestCase and the path so all modules will be tested,
137+
138+
then,
139+
140+
1. make sure that the `api_token` is updated
141+
on the `.env` file, it's needed for the
142+
access of the endpoints, else all test will simply
143+
fail, if there is such authentication
144+
145+
2. `php artisan config:cache`
146+
147+
3. `php artisan test`
148+
149+
### Database Testing
150+
This is very critical as all our tests, particularly
151+
backend API will always have the database involved.
152+
153+
In my case, because I followed the generic
154+
authentication and that token needs to be pasted
155+
so we can call the endpoints, I cannot use
156+
`Database Migrations` and `RefreshDatabase`, rather
157+
what fits in my situation is Database Transactions
158+
159+
https://laravel.com/docs/5.4/database-testing#using-transactions
160+
161+
### Why Unit Tests ?
162+
1. writing Unit Tests makes you realize that
163+
each function should do a task that can pass
164+
or fail by testing it
165+
166+
2. allows you to make functions decoupled as
167+
much as possible
168+
169+
3. it's a kind of regression testing where when
170+
you add new features to an existing system,
171+
you still are at least confident that
172+
you are not breaking the codebase by just
173+
running the unit tests and still passing them
174+
175+
As for me, the third reason is what I really like
176+
the most, because that happens all the time,
177+
you just modify or add some new feature then
178+
you realize later on, other features are broken
179+
because of that.
180+
181+
## Safely Deleting A Module
182+
using `nwidart/laravel-modules`,
183+
deleting a module should be handled correctly
184+
185+
1. `php artisan module:disable your_module_name`
186+
2. `php artisan cache:clear`
187+
3. delete module directory manually
188+
4. `php artisan cache:clear`
189+
190+
other developers that will pull these changes
191+
will simply pull it and run
192+
193+
`php artisan cache:clear`
194+
195+
## New Routes In Backend
196+
after pulling and when there are new routes in the backend,
197+
198+
`php artisan route:cache`
199+
200+
## New Package Installation
201+
When a developer installed a new package locally,
202+
the `composer.json` & `composer.lock` will be updated
203+
and this should be pushed to GitHub `main` / `master branch`
204+
205+
This way, other developers will not install it
206+
the way it was installed like
207+
208+
`composer require ...`
209+
210+
and we avoid merge conflicts in config files
211+
and to keep the same package versions.
212+
213+
Other developers will just run
214+
215+
`composer install`
216+
217+
after pulling from GitHub `main` / `master` branch.
218+
219+
Depending on the package, like if there
220+
are modified files in the `config` directory,
221+
we need to run
222+
223+
`php artisan config:cache`
224+
225+
or
226+
227+
`php artisan cache:clear`
228+
229+
for the changes to take effect.
230+
231+
## Adding New Column/s To A Table
232+
If not yet having the actual data, developers have
233+
the freedom to simply add new columns in the original
234+
migration file,
235+
236+
but this needs to be migrated as fresh
237+
238+
`php artisan migrate:fresh`
239+
240+
but we will be losing the data but
241+
since it's not actual data, this is
242+
acceptable.
243+
244+
Otherwise having the actual data on production server,
245+
we must always create a new migration file
246+
247+
`php artisan module:make-migration <add_new_column_to_table> ModuleName`
248+
249+
and simply run
250+
251+
`php artisan migrate`
252+
253+
when pushed on GitHub `master` / `main`, other developers will
254+
simply pull it and migrate too
255+
256+
and there are two conditions here:
257+
258+
1. set column to nullable - updating the content
259+
can have problems in the future particularly
260+
if there are existing data on the table, so
261+
default null to be safe
262+
263+
2. column cannot be unique - if it's null and
264+
there are existing rows that are null also
265+
then it's not unique anymore
266+
267+
after creating or editing the migration file,
268+
269+
1. we need to update the validation
270+
and sanitation code block
271+
272+
2. then finally, the Store & Update methods of the Controller
273+
274+
3. unit tests for the new column/s and
275+
functionality should be added too
276+
277+
## Database Interaction
278+
279+
### Eloquent & Laravel Query Builder
280+
In Laravel, it's best to use the `Laravel Query Builder`
281+
and the `Eloquent ORM`. Why ?
282+
283+
First is because of security,
284+
namely SQL injection.
285+
286+
Second, this unifies the syntax whether, for example,
287+
you are using MySQL or PostgreSQL.
288+
289+
### Joining Tables
290+
I usually use `LEFT JOIN` in my queries. You can
291+
left join more than two tables. Related to
292+
this is the choice whether you use Natural Key
293+
or Surrogate Key.
294+
295+
### Surrogate Key or Natural Key
296+
There is a tendency to use Natural Key as it has
297+
meaning and is straightforward. Also, you can
298+
easily implement Searching / Filtering using this.
299+
300+
But if the Natural Key has the tendency to
301+
be changed, then it's not ideal. It's a headache
302+
actually. So, for the very first time, make sure
303+
whether a Natural Key will be
304+
subjected to change or not.
305+
306+
### Database Normalization & Denormalization
307+
If you will not be reaching 100k records or more
308+
then it's sufficient to have up to 3rd Normal Form,
309+
otherwise, database structure will be too complex.
310+
Once reaching 3rd Normal Form, it's now time
311+
to denormalize to lessen the number of tables.
312+
313+
Take note also that using purely Surrogate Key
314+
violates this, particularly the 3rd Normal Form.
315+
It has no relation to the actual table data.
316+
317+
## Deploying Laravel on Test / Production Servers
318+
There are so many ways to deploy Laravel, others even
319+
have the exact configuration for Laravel only.
320+
321+
### Amazon EC2
322+
But as for me, the best is Amazon EC2 because the
323+
way you install it remotely is like the way you
324+
install it locally, the only difference is that
325+
mostly it's using Ubuntu whether it uses `Apache` or
326+
`nginx` servers. So familiarity with Linux is needed.
327+
328+
### WinSCP & PuTTY
329+
To access
330+
it remotely, we need WinSCP and it has PuTTY,
331+
an open-source terminal emulator.
332+
333+
If you know FTP, you will not find it difficult
334+
to use WinSCP, as it is an SFTP and FTP client for Windows.
335+
But not usually to transfer files particularly the code.
336+
For code, use `git pull` to pull changes from GitHub.
337+
338+
For modifying server settings, because we are using
339+
an FTP client, we can modify without
340+
using the default for Linux, like `sudo nano ...` but
341+
rather opening files much like we open it on Notepad.
342+
343+
### Git Pull or Manual File Transfer
344+
Make sure that the files you are modifying are outside
345+
your project. If that is being tracked by Git and you
346+
changed it, you can end up with merge conflicts. This will
347+
cause confusion also.
348+
349+
For all Git tracked files,
350+
modify it first in local then push to GitHub then pull to
351+
your VM. If that is VM specific code and your local will
352+
be affected, you can enclose it with a conditional, like
353+
it will check whether the `env` is production / test / local.
354+
355+
### Different ENVs
356+
Ever wonder why we have different environments ? Why, for
357+
example, we cannot use on our local a production env or test
358+
env ? Because it serves differently. For example, in local
359+
we can simply run `composer update` without being bothered much.
360+
That's not the case in production setting. So you need a local
361+
env to try things out.
362+
363+
As for the Test env, usually this has to do with testing.
364+
There is the test server that is usually being accessed by
365+
the QA team. It's like a production setup but the `debug` mode
366+
is on.
367+
368+
And finally the production environment, which does not have
369+
the debug mode. Imagine returning the details of the server
370+
and the errors / bugs. Well, you are giving the
371+
hackers the idea of the most vulnerable part of your system.
372+
373+
You don't update the production environment too, as this
374+
can ruin the entire production env. Imagine if you have
375+
version 1, and 2-3 functionalities of this are deprecated
376+
but your code is still using those functionalities then
377+
you upgraded to version 2, then
378+
boom ... you just ruin your project.
379+
380+
### Continuously Run Laravel On Test / Prod Env
381+
When in Test / Production environments, we
382+
need to run the application not with
383+
384+
`php artisan serve`
385+
386+
but rather using `pm2`
387+
388+
https://pm2.io/docs/runtime/guide/installation/
389+
390+
and follow this
391+
392+
https://awangt.medium.com/run-and-monitor-laravel-queue-using-pm2-dc4924372e03
393+
394+
it can be alongside the frontend if that is separate but
395+
on the same VM.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /