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
Git Wrapper provides a **readable API that abstracts challenges of executing Git commands from within a PHP process** for you.
9
+
10
+
- It's built upon the [`Symfony\Process`](https://symfony.com/doc/current/components/process.html) to execute the Git command with **cross-platform support** and uses the best-in-breed techniques available to PHP.
11
+
- This library also provides an SSH wrapper script and API method for developers to **easily specify a private key other than default** by using [the technique from StackOverflow](http://stackoverflow.com/a/3500308/870667).
12
+
- Finally, various commands are expected to be executed in the directory containing the working copy. **The library handles this transparently** so the developer doesn't have to think about it.
13
+
14
+
## Install
15
+
16
+
```json
17
+
composer require cpliakas/git-wrapper
18
+
```
23
19
24
20
## Usage
25
21
26
22
```php
27
23
use GitWrapper\GitWrapper;
28
24
29
-
// Initialize the library. If the path to the Git binary is not passed as
25
+
// Initialize the library. If the path to the Git binary is not passed as
30
26
// the first argument when instantiating GitWrapper, it is auto-discovered.
31
-
require_once 'vendor/autoload.php';
32
-
$wrapper = new GitWrapper();
27
+
require_once __DIR__ . '/vendor/autoload.php';
33
28
34
-
// Optionally specify a private key other than one of the defaults.
35
-
$wrapper->setPrivateKey('/path/to/private/key');
29
+
$gitWrapper = new GitWrapper();
36
30
37
-
// Clone a repo into `/path/to/working/copy`, get a working copy object.
->commit('Added the test.txt file as per the examples.')
47
-
->push();
40
+
// Add it, commit it, and push the change
41
+
$git->add('test.txt');
42
+
$git->commit('Added the test.txt file as per the examples.');
43
+
$git->push();
48
44
49
-
// Render the output.
45
+
// Render the output
50
46
print $git->getOutput();
51
47
52
48
// Stream output of subsequent Git commands in real time to STDOUT and STDERR.
53
-
$wrapper->streamOutput();
49
+
$gitWrapper->streamOutput();
54
50
55
51
// Execute an arbitrary git command.
56
52
// The following is synonymous with `git config -l`
57
-
$wrapper->git('config -l');
53
+
$gitWrapper->git('config -l');
58
54
```
59
55
60
56
All command methods adhere to the following paradigm:
@@ -69,20 +65,17 @@ passed to the Git command line tool. `$options` is an optional array of command
69
65
line options in the following format:
70
66
71
67
```php
72
-
$options = array(
68
+
$options = [
73
69
'verbose' => true, // Passes the "--verbose" flag.
74
70
't' => 'my-branch', // Passes the "-t my-branch" option.
75
-
);
71
+
];
76
72
```
77
73
78
74
#### Logging
79
75
80
-
Use the logger listener with [PSR-3](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md)
81
-
compatible loggers such as [Monolog](https://github.com/Seldaek/monolog) to log
82
-
commands that are executed.
76
+
Use the logger listener with [PSR-3](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md) compatible loggers such as [Monolog](https://github.com/Seldaek/monolog) to log commands that are executed.
// The "git.log" file now has info about the command that was executed above.
101
-
102
94
```
103
95
104
-
## Install via Composer
105
-
106
-
```json
107
-
composer require cpliakas/git-wrapper
108
-
```
109
96
110
97
## Gotchas
111
98
112
-
There are a few "gotchas" that are out of scope for this library to solve but
113
-
might prevent a successful implementation of running Git via PHP. The following
114
-
is an incomplete list of challenges that are often encountered when executing
115
-
Git from PHP.
99
+
There are a few "gotchas" that are out of scope for this library to solve but might prevent a successful implementation of running Git via PHP.
116
100
117
101
### Missing HOME Environment Variable
118
102
119
-
Sometimes the `HOME` environment variable is not set in the Git process that is
120
-
spawned by PHP. This will cause many Git operations to fail. It is advisable to
121
-
set the `HOME` environment variable to a path outside of the document root that
122
-
the web server has write access to. Note that this environment variable is only
123
-
set for the process running Git and NOT the PHP process that is spawns it.
103
+
Sometimes the `HOME` environment variable is not set in the Git process that is spawned by PHP. This will cause many Git operations to fail. It is advisable to set the `HOME` environment variable to a path outside of the document root that the web server has write access to. Note that this environment variable is only set for the process running Git and NOT the PHP process that is spawns it.
It is important that the storage is persistent as the ~/.gitconfig file will be
130
-
written to this location. See the following "gotcha" for why this is important.
109
+
It is important that the storage is persistent as the `~/.gitconfig` file will be written to this location. See the following "gotcha" for why this is important.
131
110
132
111
### Missing Identity And Configurations
133
112
134
-
Many repositories require that a name and email address are specified. This data
135
-
is set by running `git config [name] [value]` on the command line, and the
136
-
configurations are usually stored in the `~/.gitconfig file`. When executing Git
137
-
via PHP, however, the process might have a different home directory than the
138
-
user who normally runs git via the command line. Therefore no identity is sent
139
-
to the repository, and it will likely throw an error.
113
+
Many repositories require that a name and email address are specified. This data is set by running `git config [name] [value]` on the command line, and the configurations are usually stored in the `~/.gitconfig file`. When executing Git via PHP, however, the process might have a different home directory than the user who normally runs git via the command line. Therefore no identity is sent to the repository, and it will likely throw an error.
Running `git commit` on a repository with no changes returns no output but exits
154
-
with a status of 1. Therefore the library will throw a `GitException` since it
155
-
correctly detected an error. It is advisable to check whether a working copy has
156
-
any changes prior to running the commit operation in order to prevent unwanted
157
-
exceptions.
127
+
Running `git commit` on a repository *with no changes* fails with exception. To prevent that, check changes like:
158
128
159
129
```php
160
130
if ($git->hasChanges()) {
@@ -167,9 +137,5 @@ if ($git->hasChanges()) {
167
137
On checkout, the bin/git-ssh-wrapper.sh script should be executable. If it is not, git commands with fail if a non-default private key is specified.
168
138
169
139
```bash
170
-
$ chmod 0755 ./bin/git-ssh-wrapper.sh
140
+
$ chmod +x ./bin/git-ssh-wrapper.sh
171
141
```
172
-
173
-
## For Developers
174
-
175
-
Refer to [PHP Project Starter's documentation](https://github.com/cpliakas/php-project-starter#using-apache-ant) for the Apache Ant targets supported by this project.
0 commit comments