Skip to content

Commit deb823b

Browse files
MGatnerMGatner
committed
Initial docs
1 parent e5e3f8a commit deb823b

1 file changed

Lines changed: 217 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,220 @@
22
Module for updating CodeIgniter 4 projects
33

44
[![](https://github.com/tattersoftware/codeigniter4-patches/workflows/PHP%20Unit%20Tests/badge.svg)](https://github.com/tattersoftware/codeigniter4-patches/actions?query=workflow%3A%22PHP+Unit+Tests%22)
5+
6+
## Quick Start
7+
8+
1. Install with Composer: `> composer require --dev tatter/patches`
9+
2. Use the command to update: `> php spark selfupdate`
10+
11+
## Description
12+
13+
**Patches** helps keep your CodeIgniter 4 projects up-to-date when there are framework or
14+
other upstream changes that affect your project source. Use one easy command to patch your
15+
development instance and update dependencies all at once.
16+
17+
### Process
18+
19+
The library will initialize and locate any source files in **{namespace}/Patches**. Legacy
20+
files identified by the source files are copied into the workspace prior to running the update.
21+
After running updates (e.g. the equivalent of `composer update`) any files that changed are
22+
compared with their equivalent version in your project root. Any eligible files are automatically
23+
merged and then you are guided through conflict resolution in cases where a file could not be
24+
merged automatically.
25+
26+
## Installation
27+
28+
Install easily via Composer to take advantage of CodeIgniter 4's autoloading capabilities
29+
and always be up-to-date:
30+
* `> composer require --dev tatter/patches`
31+
32+
Or, install manually by downloading the source files and adding the directory to
33+
`app/Config/Autoload.php`.
34+
35+
**Note:** While **Patches** can be run in a production environment it is strongly recommended
36+
that you install it in development (using `--dev`) and then apply changes manually to production.
37+
38+
## Configuration
39+
40+
The library's default behavior can be altered by extending its config file. Copy
41+
**bin/Patches.php** to **app/Config/** and follow the instructions
42+
in the comments. If no config file is found in **app/Config** the library will use its own.
43+
44+
By default **Patches** will use its own built-in handlers for updating (Composer) and merging
45+
(Copy). You can change to another bundled handler (or write your own) using the config values.
46+
You can also disable unwanted aspects of the patching process (like Events). **Patches** will
47+
also auto-detect source files and use any available, but you can specify `ignoredSources` by
48+
their shortname (e.g. "Framework") to prevent using a source.
49+
50+
## Usage
51+
52+
**Patches** comes with a CLI Command to run patches and guide you through the process. After
53+
the module is installed and configured, run "selfupdate" from the command line:
54+
55+
php spark selfupdate
56+
57+
Follow the prompts to complete the patch process. Copies of the files are left in the workspace
58+
(default: **ROOTPATH/writable/patches/{datetime}**) along with **codex.json**, a copy of the run log.
59+
60+
## Example
61+
62+
Below is a guided example of the patch process. This shows taking [CodeIgniter Playground](https://github.com/codeigniter4projects/playground)
63+
from an earlier release of the framework up to version `4.0.3`.
64+
65+
> Add Patches to the existing project in a development setting
66+
67+
```
68+
> composer require --dev tatter/patches
69+
```
70+
71+
> All defaults are fine so kick off the patch process, which will begin with an overview of the configuration
72+
73+
```
74+
> php spark selfupdate
75+
76+
CodeIgniter CLI Tool - Version 4.0.0-rc4 - Server-Time: 2020-05-27 19:23:15pm
77+
78+
Beginning patch process
79+
Detected sources: Framework
80+
Using the following configuration:
81+
+-----------+--------------------------------------------------+
82+
| Updater | Tatter\Patches\Handlers\Updaters\ComposerHandler |
83+
| Merger | Tatter\Patches\Handlers\Mergers\CopyHandler |
84+
| Base Path | /var/www/igniter.be/patches/writable/patches |
85+
| Project | /var/www/igniter.be/patches/ |
86+
| Deletes? | Allowed |
87+
| Events? | Allowed |
88+
| Sources | Framework |
89+
| Ignored | None |
90+
+-----------+--------------------------------------------------+
91+
```
92+
93+
> The prepatch process will copy existing source files and run the update
94+
95+
```
96+
66 legacy files copied to /var/www/igniter.be/patches/writable/patches/2020-05-29-192315/legacy/
97+
98+
Loading composer repositories with package information
99+
Updating dependencies (including require-dev)
100+
Package operations: 0 installs, 1 update, 0 removals
101+
- Updating codeigniter4/framework (v4.0.0-rc4 => v4.0.3): Checking out 6d019e5354
102+
Writing lock file
103+
Generating autoload files
104+
```
105+
106+
> After the files are updated Patches analyzes changes and presents a menu based on your project's differences
107+
108+
```
109+
7 changed files detected
110+
0 added files detected
111+
0 deleted files detected
112+
113+
What would you like to do:
114+
(P)roceed with the merge
115+
(L)ist all files
116+
Show (C)hanged files (7)
117+
Show (A)dded files (0)
118+
Show (D)eleted files (0)
119+
(Q)uit
120+
Selection? [p, l, c, a, d, q]:
121+
```
122+
123+
> You can view which files were affected by typing "l" (L)
124+
125+
```
126+
+---------------------------------+---------+------+
127+
| File | Status | Diff |
128+
+---------------------------------+---------+------+
129+
| app/Config/Autoload.php | Changed | 5 |
130+
| app/Config/Boot/development.php | Changed | 3 |
131+
| app/Config/Boot/production.php | Changed | 3 |
132+
| app/Config/Boot/testing.php | Changed | 3 |
133+
| app/Config/Events.php | Changed | 13 |
134+
| app/Config/Exceptions.php | Changed | 6 |
135+
| app/Config/Services.php | Changed | 3 |
136+
+---------------------------------+---------+------+
137+
138+
No added files
139+
No deleted files
140+
```
141+
142+
> If everything looks correct, typing "p" will proceed with merge
143+
144+
```
145+
Selection? [p, l, c, a, d, q]: p
146+
5 files merged
147+
2 conflicts detected
148+
```
149+
150+
> If there were conflicts then an additional menu will prompt for conflict resolution
151+
152+
```
153+
2 conflicts detected
154+
What would you like to do:
155+
(L)ist conflict files
156+
(G)uided resolution
157+
(O)verwrite all files
158+
(S)kip all files
159+
(Q)uit
160+
```
161+
162+
> In this case Playground has a few config files with trivial modifications
163+
164+
```
165+
Selection? [l, g, o, s, q]: l
166+
+-------------------------+---------+------+
167+
| File | Status | Diff |
168+
+-------------------------+---------+------+
169+
| app/Config/Autoload.php | Changed | 5 |
170+
| app/Config/Services.php | Changed | 3 |
171+
+-------------------------+---------+------+
172+
No added files
173+
No deleted files
174+
```
175+
176+
> We will use the guided resolution to view each diff then overwrite the files
177+
178+
```
179+
Selection? [l, g, o, s, q]: g
180+
181+
This file was changed but your copy does not match the original.
182+
app/Config/Services.php
183+
(D)isplay diff
184+
(O)verwrite
185+
(S)kip
186+
(Q)uit
187+
Selection? [d, o, s, q]: d
188+
-require_once SYSTEMPATH . 'Config/Services.php';
189+
-
190+
191+
Selection? [d, o, s, q]: o
192+
```
193+
194+
> Upon completion the path to the workspace will be displayed so you can review what was accomplished
195+
196+
```
197+
Workspace with codex and files:
198+
/var/www/igniter.be/patches/writable/patches/2020-05-29-192315/
199+
```
200+
201+
> If your code is tracked you can easily see what changes were made during the patch
202+
203+
```
204+
> git status
205+
On branch patches
206+
Changes not staged for commit:
207+
(use "git add <file>..." to update what will be committed)
208+
(use "git checkout -- <file>..." to discard changes in working directory)
209+
210+
modified: app/Config/Boot/development.php
211+
modified: app/Config/Boot/production.php
212+
modified: app/Config/Boot/testing.php
213+
modified: app/Config/Events.php
214+
modified: app/Config/Exceptions.php
215+
modified: app/Config/Services.php
216+
217+
no changes added to commit (use "git add" and/or "git commit -a")
218+
219+
> git diff HEAD
220+
...
221+
```

0 commit comments

Comments
 (0)