Merge commit 'f0c77136cb044190048daf3a6df31202174fe299' as 'PHP-Parser'

Author: weynhamz

PHP-Parser/.travis.yml

@@ -0,0 +1,6 @@
+language: php
+
+php:
+ - 5.2
+ - 5.3
+ - 5.4

PHP-Parser/CHANGELOG.md

@@ -0,0 +1,82 @@
+Version 0.9.3-dev
+-----------------
+
+Nothing yet.
+
+Version 0.9.2 (07.07.2012)
+--------------------------
+* Add `Class->getMethods()` function, which returns all methods contained in the `stmts` array of the class node. This
+  does not take inherited methods into account.
+
+* Add `isPublic()`, `isProtected()`, `isPrivate()`. `isAbstract()`, `isFinal()` and `isStatic()` accessors to the
+  `ClassMethod`, `Property` and `Class` nodes. (`Property` and `Class` obviously only have the accessors relevant to
+  them.)
+
+* Fix parsing of new expressions in parentheses, e.g. `return(new Foo);`.
+
+* [BC] Due to the below changes nodes now optionally accept an `$attributes` array as the
+  last parameter, instead of the previously used `$line` and `$docComment` parameters.
+
+* Add mechanism for adding attributes to nodes in the lexer.
+
+  The following attributes are now added by default:
+
+   * `startLine`: The line the node started in.
+   * `endLine`: The line the node ended in.
+   * `comments`: An array of comments. The comments are instances of `PHPParser_Comment`
+     (or `PHPParser_Comment_Doc` for doc comments).
+
+  The methods `getLine()` and `setLine()` still exist and function as before, but internally
+  operator on the `startLine` attribute.
+
+  `getDocComment()` also continues to exist. It returns the last comment in the `comments`
+  attribute if it is a doc comment, otherwise `null`. As `getDocComment()` now returns a
+  comment object (which can be modified using `->setText()`) the `setDocComment()` method was
+  removed. Comment objects implement a `__toString()` method, so `getDocComment()` should
+  continue to work properly with old code.
+
+* [BC] Use inject-once approach for lexer:
+
+  Now the lexer is injected only once when creating the parser. Instead of
+
+        $parser = new PHPParser_Parser;
+        $parser->parse(new PHPParser_Lexer($code));
+        $parser->parse(new PHPParser_Lexer($code2));
+
+  you write:
+
+        $parser = new PHPParser_Parser(new PHPParser_Lexer);
+        $parser->parse($code);
+        $parser->parse($code2);
+
+* Fix `NameResolver` visitor to also resolve class names in `catch` blocks.
+
+Version 0.9.1 (24.04.2012)
+--------------------------
+
+* Add ability to add attributes to nodes:
+
+  It is now possible to add attributes to a node using `$node->setAttribute('name', 'value')` and to retrieve them using
+  `$node->getAttribute('name' [, 'default'])`. Additionally the existance of an attribute can be checked with
+  `$node->hasAttribute('name')` and all attributes can be returned using `$node->getAttributes()`.
+
+* Add code generation features: Builders and templates.
+
+  For more infos, see the [code generation documentation][1].
+
+* [BC] Don't traverse nodes merged by another visitor:
+
+  If a NodeVisitor returns an array of nodes to merge, these will no longer be traversed by all other visitors. This
+  behavior only caused problems.
+
+* Fix line numbers for some list structures.
+* Fix XML unserialization of empty nodes.
+* Fix parsing of integers that overflow into floats.
+* Fix emulation of NOWDOC and binary floats.
+
+Version 0.9.0 (05.01.2012)
+--------------------------
+
+First version.
+
+ [1]: https://github.com/nikic/PHP-Parser/blob/master/doc/3_Code_generation.markdown

PHP-Parser/LICENSE

@@ -0,0 +1,31 @@
+Copyright (c) 2011 by Nikita Popov.
+
+Some rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+    * The names of the contributors may not be used to endorse or
+      promote products derived from this software without specific
+      prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

PHP-Parser/README.md

@@ -0,0 +1,78 @@
+PHP Parser
+==========
+
+This is a PHP 5.4 (and older) parser written in PHP. It's purpose is to simplify static code analysis and
+manipulation.
+
+Documentation can be found in the [`doc/`][1] directory.
+
+***Note: This project is experimental, so the API is subject to change.***
+
+In a Nutshell
+-------------
+
+Basically, the parser does nothing more than turn some PHP code into an abstract syntax tree. ("nothing
+more" is kind of sarcastic here as PHP has a ... uhm, let's just say "not nice" ... grammar, which makes
+parsing PHP very hard.)
+
+For example, if you stick this code in the parser:
+
+```php
+<?php
+echo 'Hi', 'World';
+hello\world('foo', 'bar' . 'baz');
+```
+
+You'll get a syntax tree looking roughly like this:
+
+```
+array(
+    0: Stmt_Echo(
+        exprs: array(
+            0: Scalar_String(
+                value: Hi
+            )
+            1: Scalar_String(
+                value: World
+            )
+        )
+    )
+    1: Expr_FuncCall(
+        name: Name(
+            parts: array(
+                0: hello
+                1: world
+            )
+        )
+        args: array(
+            0: Arg(
+                value: Scalar_String(
+                    value: foo
+                )
+                byRef: false
+            )
+            1: Arg(
+                value: Expr_Concat(
+                    left: Scalar_String(
+                        value: bar
+                    )
+                    right: Scalar_String(
+                        value: baz
+                    )
+                )
+                byRef: false
+            )
+        )
+    )
+)
+```
+
+You can then work with this syntax tree, for example to statically analyze the code (e.g. to find
+programming errors or security issues).
+
+Additionally, you can convert a syntax tree back to PHP code. This allows you to do code preprocessing
+(like automatedly porting code to older PHP versions).
+
+So, that's it, in a nutshell. You can find everything else in the [docs][1].
+
+ [1]: https://github.com/nikic/PHP-Parser/tree/master/doc

PHP-Parser/composer.json

@@ -0,0 +1,18 @@
+{
+    "name": "nikic/php-parser",
+    "description": "A PHP parser written in PHP",
+    "keywords": ["php", "parser"],
+    "type": "library",
+    "license": "BSD",
+    "authors": [
+        {
+            "name": "Nikita Popov"
+        }
+    ],
+    "require": {
+        "php": ">=5.2"
+    },
+    "autoload": {
+        "psr-0": { "PHPParser": "lib/" }
+    }
+}

PHP-Parser/doc/0_Introduction.markdown

@@ -0,0 +1,81 @@
+Introduction
+============
+
+This project is a PHP 5.4 (and older) parser **written in PHP itself**.
+
+What is this for?
+-----------------
+
+A parser is useful for [static analysis][0] and manipulation of code and basically any other
+application dealing with code programmatically. A parser constructs an [Abstract Syntax Tree][1]
+(AST) of the code and thus allows dealing with it in an abstract and robust way.
+
+There are other ways of dealing with source code. One that PHP supports natively is using the
+token stream generated by [`token_get_all`][2]. The token stream is much more low level than
+the AST and thus has different applications: It allows to also analyize the exact formating of
+a file. On the other hand the token stream is much harder to deal with for more complex analysis.
+For example an AST abstracts away the fact that in PHP variables can be written as `$foo`, but also
+as `$$bar`, `${'foobar'}` or even `${!${''}=barfoo()}`. You don't have to worry about recognizing
+all the different syntaxes from a stream of tokens.
+
+Another questions is: Why would I want to have a PHP parser *written in PHP*? Well, PHP might not be
+a language especially suited for fast parsing, but processing the AST is much easier in PHP than it
+would be in other, faster languages like C. Furthermore the people most probably wanting to do
+programmatic PHP code analysis are incidentially PHP developers, not C developers.
+
+What can it parse?
+------------------
+
+The parser uses a PHP 5.4 compliant grammar, which is backwards compatible with at least PHP 5.3 and PHP
+5.2 (and maybe older).
+
+As the parser is based on the tokens returned by `token_get_all` (which is only able to lex the PHP
+version it runs on), additionally a wrapper for emulating new tokens from 5.3 and 5.4 is provided. This
+allows to parse PHP 5.4 source code running on PHP 5.2, for example. This emulation is very hacky and not
+yet perfect, but it should work well on any sane code.
+
+What output does it produce?
+----------------------------
+
+The parser produces an [Abstract Syntax Tree][1] (AST) also known as a node tree. How this looks like
+can best be seen in an example. The program `<?php echo 'Hi', 'World';` will give you a node tree
+roughly looking like this:
+
+```
+array(
+    0: Stmt_Echo(
+        exprs: array(
+            0: Scalar_String(
+                value: Hi
+            )
+            1: Scalar_String(
+                value: World
+            )
+        )
+    )
+)
+```
+
+This matches the semantics the program had: An echo statement, which takes two strings as expressions,
+with the values `Hi` and `World!`.
+
+You can also see that the AST does not contain any whitespace information (but most comments are saved).
+So using it for formatting analysis is not possible.
+
+What else can it do?
+--------------------
+
+Apart from the parser itself this package also bundles support for some other, related features:
+
+ * Support for pretty printing, which is the act of converting an AST into PHP code. Please note
+   that "pretty printing" does not imply that the output is especially pretty. It's just how it's
+   called ;)
+ * Support for serializing and unserializing the node tree to XML
+ * Support for dumping the node tree in a human readable form (see the section above for an
+   example of how the output looks like)
+ * Infrastructure for traversing and changing the AST (node traverser and node visitors)
+ * A node visitor for resolving namespaced names
+
+ [0]: http://en.wikipedia.org/wiki/Static_program_analysis
+ [1]: http://en.wikipedia.org/wiki/Abstract_syntax_tree
+ [2]: http://php.net/token_get_all

PHP-Parser/doc/1_Installation.markdown

@@ -0,0 +1,48 @@
+Installation
+============
+
+There are multiple ways to include the PHP parser into your project:
+
+Installing from the Zip- or Tarball
+-----------------------------------
+
+Download the latest version from [the download page][2], unpack it and move the files somewhere into your project.
+
+Installing via Composer
+-----------------------
+
+Create a `composer.json` file in your project root and use it to define your dependencies:
+
+    {
+        "require": {
+            "nikic/php-parser": "0.9.2"
+        }
+    }
+
+Then install Composer in your project (or [download the composer.phar][1] directly):
+
+    curl -s http://getcomposer.org/installer | php
+
+And finally ask Composer to install the dependencies:
+
+    php composer.phar install
+
+Installing as a PEAR package
+----------------------------
+
+Run the following two commands:
+
+    pear channel-discover nikic.github.com/pear
+    pear install channel://nikic.github.com/pear/PHPParser-0.9.2
+
+Installing as a Git Submodule
+-----------------------------
+
+Run the following command to install the parser into the `vendor/PHP-Parser` folder:
+
+    git submodule add git://github.com/nikic/PHP-Parser.git vendor/PHP-Parser
+
+
+
+ [1]: http://getcomposer.org/composer.phar
+ [2]: https://github.com/nikic/PHP-Parser/tags