You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**DISCLAIMER: We use these tools ourselves, but that doesn't mean they will necessarily work for you in your situation. This repo is public in case it can be of use to anyone else (and because it's convenient for us), but it _is not supported_ and _may change without notice_. Issues and contributions may be flat out ignored if they don't impact us. You have been warned!**
4
4
5
5
This collection of scripts is intended to provide consistency and shortcuts for common project tasks. Key tools are highlighted and described below.
6
6
7
-
* The 1.x branch is tuned for projects that primarily use git submodules for dependency management.
8
-
* The 2.x branch is meant for projects that use composer (although submodules are still supported).
7
+
* The master branch is meant for use with Cake 3 projects exclusively.
8
+
* The 2.x branch is meant for Cake 2.x projects that use composer (git submodules are still supported).
9
+
* The 1.x branch is tuned for Cake 1.x projects that use git submodules for dependency management.
9
10
* Most scripts listed below can take a `-h` option as their first argument to output usage information.
10
11
* Most are designed to run with few or no arguments; they try to guess sensible defaults whenever possible.
11
-
* Most are designed to fail gracefully. For example, if `pear` is available and your project defines a pear config file, then those dependencies will be installed by `deps-install`, otherwise pear will be silently ignored. This provides maximum flexibility without having to customize the scripts per-project.
12
+
* Most are designed to fail gracefully with a non-zero exit code.
12
13
13
14
14
-
## Requirements ##
15
+
## Requirements
15
16
16
-
The following dependencies are assumed to be available on the target system and available in the default `PATH`.
17
+
The following dependencies are assumed to be available on the target system and available via the default `$PATH`.
17
18
18
19
*`bash`
19
20
*`composer`
20
21
*`git`
21
22
*`mail`
22
23
*`mysqldump`
23
-
*`pear`
24
24
*`php`
25
25
*`realpath` (not available by default on OS X)
26
26
*`readlink`
@@ -36,107 +36,44 @@ Additionally, some scripts expect additional tools that should be automatically
36
36
If these items are not available, some scripts may not function as expected.
37
37
38
38
39
-
## Installation ##
39
+
## Installation
40
40
41
-
**WARNING!** These scripts are currently only compatible with Cake 2.x. Don't try to use them on a 1.x project.
41
+
**WARNING!** These scripts are currently only compatible with Cake 3.x. Don't try to use them on anything else.
42
42
43
-
### composer ###
44
-
45
-
Your project's own `composer.json` file should look something like this:
43
+
Your project's `composer.json` file should include something like this:
46
44
47
45
```json
48
46
{
49
-
"require": {
50
-
"loadsys/cakephp-shell-scripts": "2.0.*"
51
-
},
52
-
"config": {
47
+
"require": {
48
+
"loadsys/cakephp-shell-scripts": "~3.0"
49
+
},
50
+
"config": {
53
51
"bin-dir": "bin"
54
-
}
52
+
}
55
53
}
56
54
```
57
55
Then run `composer install` to pull this repo into your project. A `bin/` folder should be created in your project root with symlinks to all of the scripts from this package.
58
56
59
57
**Note**: The `bin-dir` is non-standard and may cause conflicts with other composer packages that install "binaries". These scripts are all expect to live in `PROJECT_ROOT/bin` though so don't expect anything to work if you forgo the `bin-dir` setting in your project.
60
58
61
-
### git submodule ###
62
-
63
-
(This is the old method and will eventually be retired.)
64
-
65
-
The scripts all expect to live together in a subfolder of your project root named `bin/`. To install them, navigate to your project root and run:
66
-
67
-
```bash
68
-
git submodule add https://github.com/loadsys/CakePHP-Shell-Scripts.git bin
69
-
```
70
-
As mentioned above, the `bin` at the end is critical. The scripts expect to be able to call each other in a folder directly inside the project root named `bin/`.
71
-
72
-
73
-
### Getting Submodule Updates ###
74
-
75
-
To pull any recent changes to the script library into your project, use the `bin/bin-selfupdate` script to update the submodule to the latest release and add the changed commit to the parent repo for you to commit.
76
-
77
-
```bash
78
-
bin/bin-selfupdate
79
-
```
80
-
81
-
If your bin/ dir does not yet have the bin-selfupdate script, you can run the following commands manually the first time:
82
-
83
-
```bash
84
-
cd bin
85
-
git pull origin master
86
-
cd ..
87
-
git add bin
88
-
git commit -m "Updated bin submodule to latest release."
89
-
```
90
-
91
-
The above changes the active commit for the submoduled bin repo, which will then be applied to other copies of the project when `git submodule update` is executed (either by `bin/update`, `bin/init-repo` or manually.)
92
59
60
+
## Contributing Improvements
93
61
94
-
## Contributing Improvements ##
95
-
96
-
**WARNING: Outside contributions are appreciated, but may be ignored if they do not impact our usage of these tools. Please consider this before sending a pull request.**
62
+
**WARNING: Outside contributions are appreciated, but may be rejected if they do not impact our usage of these tools. Please consider this before sending a pull request.**
97
63
98
64
There currently is not a convenient way to set up a test harness around this repo.
99
65
100
66
1. The best thing to do is to clone this repo (or a fork) into the `bin/` folder of an existing and established project so you have something to test against.
101
-
1. Make your edits to the scripts as necessary and commit to a feature branch.
102
-
1. If you have **added** new scripts, make sure they are executable and run `./composer-binaries` to update the composer.json file automatically (you should be using PHP 5.4 to make proper use of the `JSON_PRETTY_PRINT` flag).
67
+
1. Make your edits to the scripts as necessary and commit to a topic branch.
68
+
1. If you have **added** new scripts, make sure they are executable and run `./composer-binaries` to update the composer.json file automatically (you should be using PHP 5.4+ to make proper use of the `JSON_PRETTY_PRINT` flag).
103
69
1. Run `composer validate` to run a syntax check on the json file.
104
70
1. Submit a pull request for your branch.
105
71
106
72
107
-
## Issues ##
108
-
109
-
@TODO: Explanations below are off the cuff and need refinement.
110
-
111
-
Need to talk about the consequences and delays in how changes to this repo affect script runs in projects that include it.
112
-
113
-
For example, take a project that has already included this repo as a submodule but hasn't been updated for a while (and we've made changes to this bin repo in the meantime). When that project runs `bin/update` to update the staging copy of the app, it will be the "stale" version of bin/update that executes. That version of bin/update will eventually trigger a `git submodule update`, which might pull in changes to _itself_-- but too late for the current runtime.
73
+
## Notable Scripts
114
74
115
-
The bigger issue is that if a change to a bin/ script happens DURING the run of the stale `update` script as a result of the included `git submodules update` call, and the changes to that dependency script are incompatible with the stale version of `update`, the run will fail in unpredictable ways.
116
75
117
-
The script really needs a way of updating JUST the CakePHP-Shell-Scripts submodule **first** (and no other submodules that probably expect the codebase to be changing along with it), and if it detects any changes have been applied, exits and re-calls the newer version of itself. Seems like there is a potential for an infinite loop here if the change detection is done wrong though.
118
-
119
-
This may all be far less of an issue when we switch to composer-based installations, since it will handle the "bootstrapping" for us.
120
-
121
-
122
-
## Key Scripts ##
123
-
124
-
### bin/init-repo ###
125
-
126
-
Designed to perform all of the steps necessary to initialize a project for a developer who has just cloned the repo for the first time. (It should never be needed after that.) It performs tasks like:
127
-
128
-
* Sym-linking a Cake core into the project, if necessary.
129
-
* Copying default config files into place for the given environment.
130
-
* Writing database connection details into the `database.php` config file.
131
-
* Setting project folder ownership and write permissions.
132
-
* Initializing and updating any included git submodules.
133
-
* Applying database migrations, if present.
134
-
* Offering to load Seed data, if present.
135
-
136
-
Given an existing web-hosted folder and a database ready for use, it should fully prep a newly cloned copy of the project for use, or development.
137
-
138
-
139
-
### bin/update ###
76
+
### bin/update
140
77
141
78
Automates all of the steps for a read-only copy of the app (such as staging or production) to pull new code from the repo and update the local running copy. It performs tasks like:
142
79
@@ -152,11 +89,26 @@ Automates all of the steps for a read-only copy of the app (such as staging or p
152
89
* Showing the user the new active commit's log.
153
90
154
91
155
-
### bin/db-login ###
92
+
### bin/db-login
93
+
94
+
A simple shortcut script that uses the `[Datasources][default]` key defined in `config/app.php` to start a command line `mysql` session for you. Incredibly convenient in a production environment to run manual data queries during troubleshooting.
95
+
96
+
97
+
### bin/db-backup
98
+
99
+
Uses the default database credentials in `config/app.php` to create a ZIPed `mysqldump` of that database in a local `backups/` folder. Helpful because you don't have to specify DB credentials. It also reports the ZIP size to help you keep a mental tally over time.
100
+
101
+
102
+
### @TODO:
103
+
104
+
Add cache-clear, tests-run, docs-generate, codesniffer-run here as notable scripts.
105
+
106
+
107
+
## License
156
108
157
-
A simple shortcut script that uses the contents of `Config/database.php` to start a command line `mysql` session for you. Incredibly convenient in a production environment to run manual data queries during troubleshooting.
109
+
MIT
158
110
159
111
160
-
### bin/db-backup ###
112
+
##Copyright
161
113
162
-
Uses the default credentials in `Config/database.php` to create a ZIPed `mysqldump` of that database into a local `backups/` folder. Helpful because you don't have to specify DB credentials in multiple places.
0 commit comments