|
1 | | -A PHP Wrapper for use with the [Gitlab API](https://github.com/gitlabhq/gitlabhq/tree/master/doc/api). |
2 | | -============== |
| 1 | +# GitLab API Bundle |
3 | 2 |
|
4 | | -Based on [php-github-api](https://github.com/m4tthumphrey/php-github-api) and code from [KnpLabs](https://github.com/KnpLabs/php-github-api). |
| 3 | +[](https://travis-ci.org/scribenet/ScribeGitLabApiLibrary) |
| 4 | +[](https://codeclimate.com/github/scribenet/ScribeGitLabApiLibrary) |
| 5 | +[](https://codeclimate.com/github/scribenet/ScribeGitLabApiLibrary) |
| 6 | +[](https://gemnasium.com/scribenet/ScribeGitLabApiLibrary) |
| 7 | +[](https://packagist.org/packages/scribe/gitlab-api-library) |
| 8 | +[](LICENSE.md) |
5 | 9 |
|
6 | | -Installation |
7 | | ------------- |
8 | | -Install Composer |
| 10 | +This is a simple, object oriented PHP5 client for [GitLab's API](https://github.com/gitlabhq/gitlabhq/tree/master/doc/api), implemented with an intentionally similar API to GitLab's native RESTful API. |
9 | 11 |
|
10 | | -``` |
11 | | -$ curl -sS https://getcomposer.org/installer | php |
12 | | -$ sudo mv composer.phar /usr/local/bin/composer |
13 | | -``` |
| 12 | +## Features |
14 | 13 |
|
15 | | -Add the following to your require block in composer.json config. Note: be careful when using the `dev-master` tag as this may have unexpected results depending on your version of Gitlab. See the Versioning section below for more information. |
| 14 | +* **Code Standards**: Implements [PSR-0](http://www.php-fig.org/psr/psr-0/) code and structure standards to accommodate auto-loading using [Composer](https://getcomposer.org/) or another class auto-loading solution. |
| 15 | +* **Speed and Familiarity**: Lightweight, fast, and friendly object model utilizing lazy loading with an intentional similarly to GitLab's own RESTful API. |
| 16 | +* **Tests and Continuous Integration**: Extensive [PHPUnit](https://phpunit.de/) tests utilizing [Travis CI](https://travis-ci.org/scribenet/ScribeGitLabApiLibrary) as our continuous integration service. |
| 17 | +* **Quality, Coverage and Dependencies**: Code quality reports with [Code Climate](https://codeclimate.com/github/scribenet/ScribeGitLabApiLibrary), coverage reports with [Coveralls](https://coveralls.io/r/scribenet/ScribeGitLabApiLibrary), and dependency version monitoring using [Gemnasium](https://gemnasium.com/scribenet/ScribeGitLabApiLibrary). |
| 18 | +* **Documentation and Examples**: Comprehensive [examples](doc/) written in markdown and automatically generated [API documentationn](https://scribenet.github.io/ScribeGitLabApiLibrary/). |
16 | 19 |
|
17 | | -``` |
18 | | -"m4tthumphrey/php-gitlab-api": "dev-master" |
19 | | -``` |
| 20 | +## Requirements |
20 | 21 |
|
21 | | -Include Composer's autoloader: |
| 22 | +This library requires a short list of dependencies for both a production installation or a development build. |
22 | 23 |
|
| 24 | +### Production |
23 | 25 |
|
24 | | -```php |
25 | | -require_once dirname(__DIR__).'/vendor/autoload.php'; |
26 | | -``` |
| 26 | +* PHP >= [5.5](http://php.net/manual/en/migration55.changes.php) or [HHVM](http://hhvm.com/) |
| 27 | +* The [Curl](http://php.net/manual/en/book.curl.php) extension |
| 28 | +* The [Guzzle](https://github.com/guzzle/guzzle) [HTTP request framework](http://docs.guzzlephp.org/en/latest/) |
| 29 | +* The [Buzz](https://github.com/kriswallsmith/Buzz) HTTP request framework until the conversion to Gizzle is complete. |
27 | 30 |
|
28 | | -Versioning |
29 | | ----------- |
| 31 | +### Development |
30 | 32 |
|
31 | | -From the 6.0 stable release of Gitlab, I shall now be matching the client version with the Gitlab version. For example when Gitlab 6.1 is released I will release version 6.1.0 of the API client. If I need to make future updates to the client before the next API version is released. I will simply use a 3th build version. For example `6.1.1`, `6.1.2` etc. It is recommended that you keep your composer file up to date depending on what version of Gitlab you are currently running. So if you are using 6.0, you should required `6.0.*`; 6.1 should be `6.1.*` etc etc. |
| 33 | +* [PHPUnit](https://phpunit.de/) >= 4.0 |
| 34 | +* [Coveralls Reporter](https://github.com/satooshi/php-coveralls) >= 0.6.1 |
| 35 | +* [Code Climate Reporter](https://github.com/codeclimate/php-test-reporter) >= 0.1.2 |
| 36 | +* [Sami](https://github.com/fabpot/sami) >= 2.0 |
32 | 37 |
|
33 | | -General API Usage |
34 | | ------------------ |
| 38 | +## Installation |
35 | 39 |
|
36 | | -```php |
37 | | -$client = new \Gitlab\Client('http://git.yourdomain.com/api/v3/'); // change here |
38 | | -$client->authenticate('your_gitlab_token_here', \Gitlab\Client::AUTH_URL_TOKEN); // change here |
39 | | - |
40 | | -$project = $client->api('projects')->create('My Project', array( |
41 | | - 'description' => 'This is a project', |
42 | | - 'issues_enabled' => false |
43 | | -)); |
| 40 | +This library can be included into your project easily using [Composer](http://getcomposer.org) by adding the dependency to the `require` section of your `composer.json` project file. |
44 | 41 |
|
| 42 | +```json |
| 43 | +{ |
| 44 | + "require": { |
| 45 | + "scribe/gitlab-api-library": "dev-master" |
| 46 | + } |
| 47 | +} |
45 | 48 | ``` |
46 | 49 |
|
47 | | -Model Usage |
48 | | ------------ |
49 | | - |
50 | | -You can also use the library in an object oriented manner. |
| 50 | +## Usage |
51 | 51 |
|
52 | 52 | ```php |
53 | | -$client = new \Gitlab\Client('http://git.yourdomain.com/api/v3/'); // change here |
54 | | -$client->authenticate('your_gitlab_token_here', \Gitlab\Client::AUTH_URL_TOKEN); // change here |
55 | | -``` |
| 53 | +<?php |
56 | 54 |
|
57 | | -Creating a new project |
| 55 | +require_once 'vendor/autoload.php'; |
58 | 56 |
|
59 | | -```php |
60 | | -$project = \Gitlab\Model\Project::create($client, 'My Project', array( |
61 | | - 'description' => 'This is my project', |
62 | | - 'issues_enabled' => false |
63 | | -)); |
64 | | - |
65 | | -$project->addHook('http://mydomain.com/hook/push/1'); |
66 | | -``` |
67 | | - |
68 | | -Creating a new issue |
69 | | - |
70 | | -```php |
71 | | -$project = new \Gitlab\Model\Project(1, $client); |
72 | | -$issue = $project->createIssue('This does not work..', array( |
73 | | - 'description' => 'This doesnt work properly. Please fix', |
74 | | - 'assignee_id' => 2 |
75 | | -)); |
| 57 | +$client = new \Gitlab\Client('http://git.yourdomain.com/api/v3/'); |
| 58 | +$client->authenticate('your_gitlab_token_here', \Gitlab\Client::AUTH_URL_TOKEN); |
76 | 59 | ``` |
77 | 60 |
|
78 | | -Closing that issue |
79 | | - |
80 | | -```php |
81 | | -$issue->close(); |
82 | | -``` |
83 | | - |
84 | | -You get the idea! Take a look around and please feel free to report any bugs. |
85 | | - |
86 | | -Integration |
87 | | ------------- |
| 61 | +## Documentation |
88 | 62 |
|
89 | | -- [GitLabApiBundle](https://github.com/Zeichen32/GitLabApiBundle) Symfony2 Bundle |
| 63 | +For general usage and examples, you can check the [doc](doc/) directory. For a comprehensive API reference, check this project's [github.io webpage](https://scribenet.github.io/ScribeGitLabApiLibrary/). |
90 | 64 |
|
91 | | -Contributing |
92 | | ------------- |
| 65 | +## Contributors |
93 | 66 |
|
94 | | -There are many parts of Gitlab that I have not added to this as it was originally created for personal use, hence the lack of tests. Feel free to fork and add new functionality and tests, I'll gladly accept decent pull requests. |
| 67 | +This project has code contributed from an [array of individuals](https://github.com/scribenet/ScribeGitLabApiLibrary/graphs/contributors). |
0 commit comments