Deprecate Transfer and prepare documentation

.gitignore

@@ -6,7 +6,9 @@
 .*.sw*
 .*.un~
 nbproject
+doc/html/
 tmp/
+zf-mkdoc-theme/
 
 clover.xml
 composer.lock

.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: [email protected]
+    - 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

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/

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
+<?php
+use Zend\File\ClassFileLocator;
+
+$path = realpath(getcwd() . '/src');
+
+$locator = new ClassFileLocator($path);
+$map = [];
+
+foreach ($locator as $file) {
+    $filename = str_replace($path . '/', '', $file->getRealPath());
+    foreach ($file->getClasses() as $class) {
+        $map[$class] = $filename;
+    }
+}
+
+printf("<?php\nreturn %s;", var_export($map, true));
+```

doc/book/index.html

@@ -0,0 +1,10 @@
+<div class="container">
+  <div class="jumbotron">
+    <h1>zend-file</h1>
+
+    <p>Locate PHP classfiles.</p>
+
+    <pre><code class="language-bash">$ composer require zendframework/zend-file</code></pre>
+  </div>
+</div>
+

doc/book/index.md

@@ -0,0 +1 @@
+../../README.md

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.

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 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'

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
 {

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
 {

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
 {

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 = [

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
 {
 }

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
 {

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
 {
 }

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
 {
 }

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
 {
 }

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
 {