From 0df9d35baf02e9a05bc4e99f011abf4fcf0c2144 Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Thu, 28 Apr 2016 13:49:42 -0500 Subject: [PATCH 1/3] Prepared documentation for publication - Converted from bookdown to mkdocs - Filled in documentation for the ClassFileLocator - Added an intro, which points to the ZF1 `Zend_File_Transfer` documentation for those interested in the `Transfer` subcomponent, as well as notes the ZF2 components that provide alternatives. --- doc/book/class-file-locator.md | 60 ++++++++++++++++++++++++ doc/book/index.html | 10 ++++ doc/book/index.md | 1 + doc/book/intro.md | 26 ++++++++++ doc/book/zend.file.class-file-locator.md | 13 ----- doc/bookdown.json | 7 --- mkdocs.yml | 10 ++++ 7 files changed, 107 insertions(+), 20 deletions(-) create mode 100644 doc/book/class-file-locator.md create mode 100644 doc/book/index.html create mode 120000 doc/book/index.md create mode 100644 doc/book/intro.md delete mode 100644 doc/book/zend.file.class-file-locator.md delete mode 100644 doc/bookdown.json create mode 100644 mkdocs.yml diff --git a/doc/book/class-file-locator.md b/doc/book/class-file-locator.md new file mode 100644 index 0000000..7929ae0 --- /dev/null +++ b/doc/book/class-file-locator.md @@ -0,0 +1,60 @@ +# ClassFileLocator + +`Zend\File\ClassFileLocator` is a PHP [FilterIterator](http://php.net/FilterIterator) +for use with locating files containing PHP classes, interfaces, abstracts, or +traits. As such, it should be used in conjunction with a +[DirectoryIterator](http://php.net/DirectoryIterator) or +[RecursiveDirectoryIterator](http://php.net/RecursiveDirectoryIterator). + +Use cases include building class maps for autoloading. + +## Usage + +The `ClassFileLocator` constructor can take one of: + +- a string representing a directory location; if valid, this will be used to + seed a `RecursiveDirectoryIterator` instance. +- a `DirectoryIterator` instance. +- a `RecursiveDirectoryIterator` instance. + +In each case, once constructed, iteration will result in a list of files +containing PHP clases, interfaces, abstracts, or traits. + +Instead of returning standard [SplFileInfo](http://php.net/SplFileInfo) +instances, the `ClassFileLocator` is configured to cast to +`Zend\File\PhpClassFile` instances, which extend `SplFileInfo`, and provide the +following additional methods: + +- `getClasses()`: returns an array of all classes, abstract classes, interfaces, + and traits defined in the file; all names are fully qualified. +- `getNamespaces()`: returns an array of namespaces defined in the file. + +> ### Tokenization +> +> The `ClassFileLocator` uses the [tokenizer](http://php.net/tokenizer) +> extension in order to locate items of interest; as such, its operations +> will not execute PHP files it finds. + +## Example + +The following will spit out a PHP file that returns a class map for the `src/` +directory in which it is run: + +```php +getRealPath()); + foreach ($file->getClasses() as $class) { + $map[$class] = $filename; + } +} + +printf(" +
+

zend-file

+ +

Locate PHP classfiles, and manage file uploads.

+ + 
$ composer require zendframework/zend-file
+
+ + diff --git a/doc/book/index.md b/doc/book/index.md new file mode 120000 index 0000000..fe84005 --- /dev/null +++ b/doc/book/index.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/doc/book/intro.md b/doc/book/intro.md new file mode 100644 index 0000000..264f954 --- /dev/null +++ b/doc/book/intro.md @@ -0,0 +1,26 @@ +# Introduction + +zend-file provides two specific pieces of functionality: + +- a `ClassFileLocator`, which can be used to find PHP class files under a given + tree. +- a `Transfer` subcomponent, for managing file uploads and reporting upload + progress. + +**The `Transfer` subcomponent is deprecated**, and we recommend using the +file-related functionality in: + +- [zend-filter](https://zendframework.github.io/zend-filter/), which provides + functionality around moving uplaoded files to their final locations, renaming + uploaded files, and encrypting and decrypting uploaded files. +- [zend-validator](https://github.com/zendframework/zend-validator/), which + provides functionality around validating uploaded files based on: number of + files uploaded, MIME types and/or extensions, upload status, compression, + hashing, and more. +- [zend-progressbar](https://github.com/zendframework/zend-progressbar/), which + provides functionality for providing file upload status. + +If you are determined to use the `Transfer` subcomponent, despite its +deprecation, please see the [Zend Framework 1 documentation on the component](http://framework.zend.com/manual/1.12/en/zend.file.transfer.introduction.html); +you can substitute `Underscore_Separated_Names` for their namespaced equivalents +to adapt the examples to this component. diff --git a/doc/book/zend.file.class-file-locator.md b/doc/book/zend.file.class-file-locator.md deleted file mode 100644 index e5026ab..0000000 --- a/doc/book/zend.file.class-file-locator.md +++ /dev/null @@ -1,13 +0,0 @@ -# Zend\\File\\ClassFileLocator - -## Overview - -TODO - -## Available Methods - -TODO - -## Examples - -TODO diff --git a/doc/bookdown.json b/doc/bookdown.json deleted file mode 100644 index 85b5b25..0000000 --- a/doc/bookdown.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "title": "Zend\\File", - "target": "html/", - "content": [ - "book/zend.file.class-file-locator.md" - ] -} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..33f6149 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,10 @@ +docs_dir: doc/book +site_dir: doc/html +pages: + - index.md + - Intro: intro.md + - ClassFileLocator: class-file-locator.md +site_name: zend-file +site_description: zend-file +repo_url: 'https://github.com/zendframework/zend-file' +copyright: 'Copyright (c) 2016 Zend Technologies USA Inc.' From c5f7df5f7903cb6ede038b3b16c9461cf9918657 Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Thu, 28 Apr 2016 14:00:06 -0500 Subject: [PATCH 2/3] Marked all classes under the Transfer subcomponent as deprecated --- README.md | 6 +++--- doc/book/index.html | 2 +- src/Transfer/Adapter/AbstractAdapter.php | 2 +- src/Transfer/Adapter/FilterPluginManager.php | 1 + src/Transfer/Adapter/Http.php | 1 + src/Transfer/Adapter/ValidatorPluginManager.php | 3 +++ src/Transfer/Exception/BadMethodCallException.php | 3 +++ src/Transfer/Exception/ExceptionInterface.php | 1 + src/Transfer/Exception/InvalidArgumentException.php | 3 +++ src/Transfer/Exception/PhpEnvironmentException.php | 3 +++ src/Transfer/Exception/RuntimeException.php | 3 +++ src/Transfer/Transfer.php | 1 + 12 files changed, 24 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4f83238..b8f18ac 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ [![Build Status](https://secure.travis-ci.org/zendframework/zend-file.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-file) [![Coverage Status](https://coveralls.io/repos/zendframework/zend-file/badge.svg?branch=master)](https://coveralls.io/r/zendframework/zend-file?branch=master) -`Zend\File` is a component used to manage file transfer and class autoloading. - +zend-file provides a `ClassFileLocator` for locating PHP files containing +classes, abstract classes, interfaces, and traits in a specified tree. - File issues at https://github.com/zendframework/zend-file/issues -- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-file +- Documentation is at https://zendframework.github.io/zend-file/ diff --git a/doc/book/index.html b/doc/book/index.html index f02659d..7f8e88e 100644 --- a/doc/book/index.html +++ b/doc/book/index.html @@ -2,7 +2,7 @@

zend-file

-

Locate PHP classfiles, and manage file uploads.

+

Locate PHP classfiles.

$ composer require zendframework/zend-file
diff --git a/src/Transfer/Adapter/AbstractAdapter.php b/src/Transfer/Adapter/AbstractAdapter.php index 0278d60..0d80a3b 100644 --- a/src/Transfer/Adapter/AbstractAdapter.php +++ b/src/Transfer/Adapter/AbstractAdapter.php @@ -30,7 +30,7 @@ * modifying that should be done in tandem with a rewrite to utilize validator * and filter chains instead. * - * @todo Rewrite + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 */ abstract class AbstractAdapter implements TranslatorAwareInterface { diff --git a/src/Transfer/Adapter/FilterPluginManager.php b/src/Transfer/Adapter/FilterPluginManager.php index 8c8f93e..21d8a80 100644 --- a/src/Transfer/Adapter/FilterPluginManager.php +++ b/src/Transfer/Adapter/FilterPluginManager.php @@ -18,6 +18,7 @@ * Enforces that filters retrieved are instances of * FilterInterface. Additionally, it registers a number of default filters. * + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 */ class FilterPluginManager extends BaseManager { diff --git a/src/Transfer/Adapter/Http.php b/src/Transfer/Adapter/Http.php index 96e26cd..42ea3c1 100644 --- a/src/Transfer/Adapter/Http.php +++ b/src/Transfer/Adapter/Http.php @@ -17,6 +17,7 @@ /** * File transfer adapter class for the HTTP protocol * + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 */ class Http extends AbstractAdapter { diff --git a/src/Transfer/Adapter/ValidatorPluginManager.php b/src/Transfer/Adapter/ValidatorPluginManager.php index 5cc1508..ed24520 100644 --- a/src/Transfer/Adapter/ValidatorPluginManager.php +++ b/src/Transfer/Adapter/ValidatorPluginManager.php @@ -12,6 +12,9 @@ use Zend\Validator\File; use Zend\Validator\ValidatorPluginManager as BaseManager; +/** + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 + */ class ValidatorPluginManager extends BaseManager { protected $defaultFileValidationAliases = [ diff --git a/src/Transfer/Exception/BadMethodCallException.php b/src/Transfer/Exception/BadMethodCallException.php index ed9d017..be9cecb 100644 --- a/src/Transfer/Exception/BadMethodCallException.php +++ b/src/Transfer/Exception/BadMethodCallException.php @@ -11,6 +11,9 @@ use Zend\File\Exception; +/** + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 + */ class BadMethodCallException extends Exception\BadMethodCallException implements ExceptionInterface { } diff --git a/src/Transfer/Exception/ExceptionInterface.php b/src/Transfer/Exception/ExceptionInterface.php index 827196b..360b948 100644 --- a/src/Transfer/Exception/ExceptionInterface.php +++ b/src/Transfer/Exception/ExceptionInterface.php @@ -14,6 +14,7 @@ /** * Exception class for Zend\File\Transfer * + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 */ interface ExceptionInterface extends FileException { diff --git a/src/Transfer/Exception/InvalidArgumentException.php b/src/Transfer/Exception/InvalidArgumentException.php index 63999e3..a9325b8 100644 --- a/src/Transfer/Exception/InvalidArgumentException.php +++ b/src/Transfer/Exception/InvalidArgumentException.php @@ -11,6 +11,9 @@ use Zend\File\Exception; +/** + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 + */ class InvalidArgumentException extends Exception\InvalidArgumentException implements ExceptionInterface { } diff --git a/src/Transfer/Exception/PhpEnvironmentException.php b/src/Transfer/Exception/PhpEnvironmentException.php index 8a35846..5d28f72 100644 --- a/src/Transfer/Exception/PhpEnvironmentException.php +++ b/src/Transfer/Exception/PhpEnvironmentException.php @@ -9,6 +9,9 @@ namespace Zend\File\Transfer\Exception; +/** + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 + */ class PhpEnvironmentException extends RuntimeException { } diff --git a/src/Transfer/Exception/RuntimeException.php b/src/Transfer/Exception/RuntimeException.php index 29dcc84..f2f3275 100644 --- a/src/Transfer/Exception/RuntimeException.php +++ b/src/Transfer/Exception/RuntimeException.php @@ -11,6 +11,9 @@ use Zend\File\Exception; +/** + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 + */ class RuntimeException extends Exception\RuntimeException implements ExceptionInterface { } diff --git a/src/Transfer/Transfer.php b/src/Transfer/Transfer.php index 3e89056..595c527 100644 --- a/src/Transfer/Transfer.php +++ b/src/Transfer/Transfer.php @@ -12,6 +12,7 @@ /** * Base class for all protocols supporting file transfers * + * @deprecated since 2.7.0, and scheduled for removal with 3.0.0 */ class Transfer { From 8a897b009c2b4692561192f7f3994a9d4e17b30b Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Thu, 28 Apr 2016 14:07:01 -0500 Subject: [PATCH 3/3] Added documentation build automation --- .gitignore | 2 ++ .travis.yml | 18 +++++++++++++++++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index a7fc91d..f146c86 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,9 @@ .*.sw* .*.un~ nbproject +doc/html/ tmp/ +zf-mkdoc-theme/ clover.xml composer.lock diff --git a/.travis.yml b/.travis.yml index 34dad1d..17b5bc7 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,12 +4,22 @@ language: php branches: except: - - /^release-.*$/ + - /^release-\d+\.\d+\.\d+.*$/ - /^ghgfk-.*$/ cache: directories: - $HOME/.composer/cache + - $HOME/.local + - zf-mkdoc-theme + +env: + global: + - SITE_URL: https://zendframework.github.io/zend-file + - GH_USER_NAME: "Matthew Weier O'Phinney" + - GH_USER_EMAIL: matthew@weierophinney.net + - GH_REF: github.com/zendframework/zend-file.git + - secure: "ULsxLLRxxpphEwpOfpTWzW85g8LLoCsa9M5g2fiWlKhvl+FjfvSTkMmDHCzNq6QSfASpI+MTyZBxj34v8Fqq/U82IXCfoHP1mFYw//5qg6Xm28nVz48chjjCD5eIzKNI6vIdY+S+mhstcAkl3AqXAczsIxK34B6BZQxWOUUnDAn/jJ2bPpyiI/laePt76jel8xeMjNYrnIV9VvwsK9klttEOifMyK1pnGgTf8OvPD4WNaaiFLroE1JGFJJrbnColabFjXIQbKRupGpNp/Cz6Nn0M3I8Da1sSa1zeq4485c2eR61rJ7HXUX769wvPakDgrMjAGcIZGwvzfPqD0ldefXU2gsRpom4p7wUxQGndyQAF3ytUFn5QBz8TRPQ1AIT2uIsd3dblvqFn17HAPSKNihX4F9xkSogp/D5znYYwrZ3hrjZRY9idRJqDYkDV2/VTu1RiKI/SukPj2wTLxQwZttxHFhJapjKDzJ289TekA2ShBewCNR+3gl9uetzb0ir4C8l3TWo40fBjG8SMxan4y48EdOetAoWwjnigTnR0aXA/Mgm0Ly/ide1Xuho12P/cj54EWdmE+5LTUd70O0oBp0sLRZG6S3Wz0jRy4Z7XvbXCaoIBXHcmFjPOyfcmjgh0BBkHM0Ir8Cwe5CgwpaMQnUjw8nRDdG+TC62UczOyoHo=" matrix: fast_finish: true @@ -23,6 +33,8 @@ matrix: - php: 5.6 env: - EXECUTE_TEST_COVERALLS=true + - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)" + - PATH="$HOME/.local/bin:$PATH" - php: 5.6 env: - ZEND_SERVICEMANAGER_VERSION="^2.7.5" @@ -55,6 +67,10 @@ script: - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi + - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi + +after_success: + - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi after_script: - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi