Merge branch 'hotfix/11'

Close #11
Close #12

.coveralls.yml

@@ -1,3 +1,2 @@
 coverage_clover: clover.xml
 json_path: coveralls-upload.json
-src_dir: src

.gitattributes

@@ -4,5 +4,5 @@
 .gitattributes export-ignore
 .gitignore export-ignore
 .travis.yml export-ignore
-.php_cs export-ignore
+phpcs.xml export-ignore
 phpunit.xml.dist export-ignore

.gitignore

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

.travis.yml

@@ -10,6 +10,16 @@ branches:
 cache:
   directories:
     - $HOME/.composer/cache
+    - $HOME/.local
+    - zf-mkdoc-theme
+
+env:
+  global:
+    - SITE_URL: https://zendframework.github.io/zend-memory
+    - GH_USER_NAME: "Matthew Weier O'Phinney"
+    - GH_USER_EMAIL: [email protected]
+    - GH_REF: github.com/zendframework/zend-memory.git
+    - secure: "QsaJwTAeNgLt3HlCLHsMy43lSLQsYym0lbvmMbSZd0ykJt/2ViNjCM9xwRDIGsYYFCGZRqUITeKgnF9sMh43hsMwLryvdN3jQGw/4MmS9QXPpb74kWgm1s2McCnD0XtuSAtxGkUZGCbqJXciAEpj+bc1iXkPvmtxt3mFrSILTiYK6U70HNp7K7Agx6bVhJ0sy7AK273bQzyQDmi1aNhzFd+prZtN6UO2dEpdNk5cRL9m8zp7lz9Wk4DWUDQRjp1B01hk72vqOkLaGXDyH+vhoZ2lNUrgERe81BAl2mmgI1KEZl3itMuWHGlEr0YAntyHeJgK+ThfghKzTgDeUXQ2slXp7V9KM/VXQLRkxydZp1h7oTl9Fc0I0CLUUvrDoH3gxB/+W7xBdYy3pkyD02C0QL13HBnOLr8SdZXxH5Crf6dwHl4qcT1/FUuggdDAc98IG3Xp5p4dt6lIJHaJvlBe9KkSt7CEPDTZWByHf3j51EDc7XmkdoVl4zfqm4FiURdFAnC9EUFEksolaI7tBpd2CKfy4EIEw2eycTBjp+WDAzLTFRwAib3GQlEEZjZFu6MWmQy5EF44JCLgOxiBRKwHzm22qQjt1SVftH3fZNHVvU2BQ6UEuzy+PxcKIjnasobGijtj14ns49PDxVxbfJb7SgKKeKGNOTUFyH+6VmgFJg0="
 
 matrix:
   fast_finish: true
@@ -20,10 +30,11 @@ 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: 7
     - php: hhvm 
   allow_failures:
-    - php: 7
     - php: hhvm
 
 notifications:
@@ -39,9 +50,13 @@ install:
   - travis_retry composer install --no-interaction --ignore-platform-reqs
 
 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 [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then composer test-coverage ; fi
+  - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then composer test ; fi
+  - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then composer cs-check ; 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
+  - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then composer upload-coverage ; fi

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file, in reverse chronological order by release.
+
+## 2.5.2 - 2016-05-11
+
+### Added
+
+- [#11](https://github.com/zendframework/zend-memory/pull/11) and
+  [#12](https://github.com/zendframework/zend-memory/pull/12) add and publish
+  the documentation to https://zendframework.github.io/zend-memory/
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- [#12](https://github.com/zendframework/zend-memory/pull/12) updates the
+  PHP requirement to allow either 5.5+ or 7.0+, and pins the zend-cache version
+  for testing to 2.7+.

README.md

@@ -3,17 +3,15 @@
 [![Build Status](https://secure.travis-ci.org/zendframework/zend-memory.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-memory)
 [![Coverage Status](https://coveralls.io/repos/zendframework/zend-memory/badge.svg?branch=master)](https://coveralls.io/r/zendframework/zend-memory?branch=master)
 
-The `Zend\Memory` component is intended to manage data in an environment with
-limited memory.
+zend-memory manages data in an environment with limited memory.
 
-Memory objects (memory containers) are generated by memory manager by request
-and transparently swapped/loaded when it’s necessary.
+Memory objects (memory containers) are generated by the memory manager, and
+transparently swapped/loaded when required.
 
 For example, if creating or loading a managed object would cause the total memory
 usage to exceed the limit you specify, some managed objects are copied to cache
 storage outside of memory. In this way, the total memory used by managed objects
 does not exceed the limit you need to enforce.
 
-
 - File issues at https://github.com/zendframework/zend-memory/issues
-- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-memory
+- Documentation is at https://zendframework.github.io/zend-memory/

composer.json

@@ -13,15 +13,15 @@
         }
     },
     "require": {
-        "php": ">=5.5"
+        "php": "^5.5 || ^7.0"
     },
     "require-dev": {
-        "zendframework/zend-cache": "~2.5",
-        "fabpot/php-cs-fixer": "1.7.*",
-        "phpunit/PHPUnit": "~4.0"
+        "zendframework/zend-cache": "^2.7",
+        "squizlabs/php_codesniffer": "^2.3.1",
+        "phpunit/PHPUnit": "^4.8"
     },
     "suggest": {
-        "zendframework/zend-cache": "To support swap the memory objects"
+        "zendframework/zend-cache": "To support swapping memory objects into and out of non-memory cache storage"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,
@@ -35,5 +35,16 @@
         "psr-4": {
             "ZendTest\\Memory\\": "test/"
         }
+    },
+    "scripts": {
+        "check": [
+            "@cs-check",
+            "@test"
+        ],
+        "upload-coverage": "coveralls -v",
+        "cs-check": "phpcs",
+        "cs-fix": "phpcbf",
+        "test": "phpunit",
+        "test-coverage": "phpunit --coverage-clover clover.xml"
     }
-}
+}

doc/book/index.html

@@ -0,0 +1,12 @@
+<div class="container">
+    <div class="jumbotron">
+        <h1>zend-memory</h1>
+
+        <p>
+            Manage data in an environment with limited memory.
+        </p>
+
+        <pre><code class="language-bash">$ composer require zendframework/zend-memory</code></pre>
+    </div>
+</div>
+

doc/book/index.md

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

doc/book/intro.md

@@ -0,0 +1,113 @@
+# Introduction
+
+zend-memory assists with managing data in an environment with limited memory.
+
+Memory objects (memory containers) are generated by the memory manager at your
+request and transparently swapped/loaded when necessary.
+
+For example, if creating or loading a managed object would cause the total
+memory usage to exceed the limit you specify, some managed objects are copied to
+cache storage outside of memory. In this way, the total memory used by managed
+objects does not exceed the limit you need to enforce. To provide this
+functionality, the memory manager can compose [zend-cache storage adapters](http://zendframework.github.io/zend-cache/storage/adapter/)
+as storage providers.
+
+## Usage
+
+Instantiate the memory manager class:
+
+```php
+use Zend\Memory\MemoryManager;
+
+// No caching backend:
+$memoryManager = new MemoryManager();
+```
+
+Optionally, you can create a cache storage adapter, and pass it to the
+`MemoryManager` constructor:
+
+```php
+use Zend\Cache\StorageFactory;
+use Zend\Memory\MemoryManager;
+
+// Use a filesystem adapter, placing memory blocks in the tmp directory
+// under which the application is running.
+$cache = StorageFactory::factory([
+    'adapter' => [
+        'name' => 'filesystem',
+        'options' => ['cache_dir' => './tmp/'],
+    ],
+]);
+
+$memoryManager = new MemoryManager($cache);
+```
+
+Once you have a `MemoryManager` instance, you can start pushing values to it and
+pulling values from it.
+
+```php
+$loadedFiles = array();
+
+for ($count = 0; $count < 10000; $count++) {
+    $f = fopen($fileNames[$count], 'rb');
+    $data = fread($f, filesize($fileNames[$count]));
+    $fclose($f);
+
+    $loadedFiles[] = $memoryManager->create($data);
+}
+
+echo $loadedFiles[$index1]->value;
+
+$loadedFiles[$index2]->value = $newValue;
+
+$loadedFiles[$index3]->value[$charIndex] = '_';
+```
+
+## Theory of Operation
+
+zend-memory operates with the following concepts:
+
+- Memory manager
+- Memory container
+  - Locked memory object
+  - Movable memory object
+
+### Memory manager
+
+The memory manager generates memory objects (locked or movable) by request of
+the application, and returns them wrapped into a memory container object.
+
+### Memory container
+
+The memory container has a virtual or actual `value` attribute of type `string`.
+This attribute contains the data value specified at memory object creation time.
+
+You can operate with this `value` attribute as an object property:
+
+```php
+$memObject = $memoryManager->create($data);
+
+echo $memObject->value;
+
+$memObject->value = $newValue;
+
+$memObject->value[$index] = '_';
+
+echo ord($memObject->value[$index1]);
+
+$memObject->value = substr($memObject->value, $start, $length);
+```
+
+### Locked memory
+
+Locked memory objects are always stored in memory. Data stored in locked memory
+are never swapped to the cache backend.
+
+### Movable memory
+
+Movable memory objects are transparently swapped and loaded to/from the cache
+backend by the `MemoryManager` when necessary.
+
+The memory manager does not swap objects with size less than the specified
+minimum, due to performance considerations. See [the settings section](memory-manager.md#settings)
+for more details.