Merge pull request #97 from marcelog/v2.0.0

V2.0.0

.codeclimate.yml

@@ -0,0 +1,19 @@
+engines:
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - php
+  fixme:
+    enabled: false
+  phpcodesniffer:
+    enabled: true
+  phpmd:
+    enabled: true
+
+ratings:
+  paths:
+  - "**.php"
+
+exclude_paths:
+- test/**/*

.gitignore

@@ -1,3 +1,4 @@
+composer.lock
 vendor
 .buildpath
 .project

.travis.yml

@@ -0,0 +1,23 @@
+language: php
+php:
+  - '5.4'
+  - '5.5'
+  - '5.6'
+  - '7.0'
+
+before_script:
+  - phpenv config-add test/resources/php.ini
+
+install:
+  - composer install
+
+script:
+  - vendor/bin/phing travis
+
+after_script:
+  - travis_retry php vendor/bin/coveralls -v
+  - vendor/bin/test-reporter
+
+addons:
+  code_climate:
+    repo_token: 5d81d5163c7f9b810b46451042cb0069d24c91a5887466ba774bf89a56f0187e

README.md

@@ -1,5 +1,14 @@
-Introduction
-============
+[![License](https://poser.pugx.org/marcelog/PAMI/license)](https://packagist.org/packages/marcelog/PAMI)
+[![Latest Stable Version](https://poser.pugx.org/marcelog/PAMI/v/stable)](https://packagist.org/packages/marcelog/PAMI)
+[![Documentation Status](https://readthedocs.org/projects/pami/badge/?version=latest)](http://pami.readthedocs.org/en/latest/?badge=latest)
+
+[![Build Status](https://travis-ci.org/marcelog/PAMI.svg)](https://travis-ci.org/marcelog/PAMI)
+[![Coverage Status](https://coveralls.io/repos/marcelog/PAMI/badge.svg?branch=master&service=github)](https://coveralls.io/github/marcelog/PAMI?branch=master)
+[![Code Climate](https://codeclimate.com/github/marcelog/PAMI/badges/gpa.svg)](https://codeclimate.com/github/marcelog/PAMI)
+[![Issue Count](https://codeclimate.com/github/marcelog/PAMI/badges/issue_count.svg)](https://codeclimate.com/github/marcelog/PAMI)
+
+# Introduction
+
 PAMI means PHP Asterisk Manager Interface. As its name suggests its just a
 set of php classes that will let you issue commands to an ami and/or receive
 events, using an observer-listener pattern.
@@ -10,85 +19,44 @@ either via SOA or ajax.
 A port for nodejs is available at: http://marcelog.github.com/Nami
 A port for erlang is available at: https://github.com/marcelog/erlami
 
--------------------------------------------------------------------------------
+# Contact me
 
-Contact me
-----------
 If you have any questions, issues, feature requests, or just want to report
 your "success story", or maybe even say hi, please send an email to
 [email protected]
 
 Also, checkout the [Complete PAGI/PAMI talk for the PHP Conference Argentina 2013](http://www.slideshare.net/mgornstein/phpconf-2013). Check the slide notes for the complete text :)
 
--------------------------------------------------------------------------------
+# PHP Versions
 
-PHP Versions
-------------
 Note: PAMI Requires PHP 5.3+. PHP versions 5.3.9 and 5.3.10 WILL NOT WORK due
 to a bug introduced in stream_get_line() in 5.3.9. Please use 5.3.11+ or up
 to 5.3.8 (see README.PHP-5.3.9-and-5.3.10).
 
--------------------------------------------------------------------------------
-
-CI Server
----------
-Take a look at the Jenkins CI Server (http://ci.marcelog.name/) to check out
-the docs, metrics, and pear and phar packages available.
-
--------------------------------------------------------------------------------
-
-Available via Composer
-----------------------
-Just add the package "marcelog/pami":
-```
-    "require": {
-        "marcelog/pami": "dev-master"
-    }
-```
-Packagist URL: http://packagist.org/packages/marcelog/pami
-
--------------------------------------------------------------------------------
-
-Available via PEAR
-------------------
-You can now easily install PAMI by issuing:
-```
-# pear channel-discover pear.marcelog.name
-# pear install marcelog/PAMI
-```
-
-or
-```
-# pear install marcelog/PAMI-1.72
+# Installing
+Add this library to your [Composer](https://packagist.org/) configuration. In
+composer.json:
+```json
+  "require": {
+    "marcelog/pami": "2.*"
+  }
 ```
-just replace 1.72 by the release version you'd like to install :)
-See: http://pear.marcelog.name/
-
--------------------------------------------------------------------------------
 
-Available as PHAR
------------------
-Just go to the Jenkins server at http://ci.marcelog.name and grab the latest
-phar distribution from the PAMI job.
+# Asterisk versions supported
 
--------------------------------------------------------------------------------
-
-Asterisk versions supported
-===========================
 PAMI is tested in asterisk 1.6, 1.4, and 1.8 versions, just because this are
 the versions I use in my boxes. If you need support for other versions, please
 contact me.
 
--------------------------------------------------------------------------------
+# QuickStart
 
-QuickStart
-==========
 For an in-depth tutorial: http://marcelog.github.com/articles/pami_introduction_tutorial_how_to_install.html
 
 ```
+// Make sure you include the composer autoload.
+require __DIR__ . '/vendor/autoload.php';
+
 $options = array(
-    'log4php.properties' =>
-         RESOURCES_DIR . DIRECTORY_SEPARATOR . 'log4php.properties',
     'host' => '2.3.4.5',
     'scheme' => 'tcp://',
     'port' => 9999,
@@ -110,12 +78,9 @@ $client->registerEventListener(array($listener, 'handle'));
 $client->registerEventListener($listener);
 ```
 
--------------------------------------------------------------------------------
-
-Using Predicates
-================
+# Using Predicates
 A second (optional) argument can be used when registering the event listener: a
-closure that will be evaluated before calling the callback. The callback will 
+closure that will be evaluated before calling the callback. The callback will
 be called only if this predicate returns true:
 
 ```
@@ -129,10 +94,8 @@ $client->registerEventListener(
 );
 ```
 
--------------------------------------------------------------------------------
+# Example
 
-Example
-=======
 Please see docs/examples/quickstart/example.php for a very basic example.
 
 AsterTrace is a full application: https://github.com/marcelog/AsterTrace.
@@ -143,10 +106,8 @@ For an example of using asynchronous AGI with PAMI, see docs/examples/asyncagi
 
 The [march edition](http://sdjournal.org/a-practical-introduction-to-functional-programming-with-php-sdj-issue-released/) of [Software Developer Journal](http://sdjournal.org/) features a complete article about writing telephony applications with PAMI and PAGI.
 
--------------------------------------------------------------------------------
+# Currently Supported Events
 
-Currently Supported Events
-==========================
 More events will be added with time. I can only add the ones I can test for and
 use, so your contributions may make the difference! ;)
 
@@ -230,10 +191,8 @@ can still catch them. If you catch one of these, please report it!
 * VoicemailUserEntry
 * VoicemailUserEntryComplete
 
--------------------------------------------------------------------------------
+# Currently Supported Actions
 
-Currently Supported Actions
-===========================
 * AbsoluteTimeout
 * AGI
 * Agents
@@ -322,36 +281,47 @@ Currently Supported Actions
 * VGSM_SMS_TX
 * VoicemailUsersList
 
--------------------------------------------------------------------------------
 
-Developers
-==========
 
-* build.xml is a phing build file, not ant.
-* It's very possible that you may need to edit build.properties and change
-php.bin and pear.bin properties.
-* Available main targets: all, build, test, report.
-* Tools run: phpdoc, phploc, phpcs, phpmd, phpcpd, phpdepend, phpunit.
-* Setup your installation by editing pear and php paths in build.properties
-* Run phing install-dependencies this will install pear and everything needed
-to run phing tests and metrics.
-* Copy resources/php.ini.example to resources/php.ini and edit it.
-* Run phing all
-* Check the API at http://marcelog.github.com/PAMI/api.html
+## Debugging, logging
+
+You can optionally set a [PSR-3](http://www.php-fig.org/psr/psr-3/) compatible logger:
+```php
+$pami->setLogger($logger);
+```
+
+By default, the client will use the [NullLogger](http://www.php-fig.org/psr/psr-3/#1-4-helper-classes-and-interfaces).
 
--------------------------------------------------------------------------------
+# Developers
+This project uses [phing](https://www.phing.info/). Current tasks include:
+ * test: Runs [PHPUnit](https://phpunit.de/).
+ * cs: Runs [CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer).
+ * doc: Runs [PhpDocumentor](http://www.phpdoc.org/).
+ * md: runs [PHPMD](http://phpmd.org/).
+ * build: This is the default task, and will run all the other tasks.
 
-Debugging, logging
-==================
+## Running a phing task
+To run a task, just do:
 
-You need log4php (http://logging.apache.org/log4php/). Just make sure you copy
-it to the include_path and PAMI will pick it up from there.
+```sh
+vendor/bin/phing build
+```
 
--------------------------------------------------------------------------------
+## Contributing
+To contribute:
+ * Make sure you open a **concise** and **short** pull request.
+ * Throw in any needed unit tests to accomodate the new code or the
+ changes involved.
+ * Run `phing` and make sure everything is ok before submitting the pull
+ request (make phpmd and CodeSniffer happy, also make sure that phpDocumentor
+ does not throw any warnings, since all our documentation is automatically
+ generated).
+ * Your code must comply with [PSR-2](http://www.php-fig.org/psr/psr-2/),
+ CodeSniffer should take care of that.
 
 LICENSE
 =======
-Copyright 2011 Marcelo Gornstein <[email protected]>
+Copyright 2016 Marcelo Gornstein <[email protected]>
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -365,10 +335,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 
--------------------------------------------------------------------------------
-
-Thanks To
-=========
+# Thanks To
 
 * Jason Blank <rumpled at github> for helping in the debugging of the queue
 functionality and some other ami inconsistencies.