will/KnpGaufretteBundle
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #52 from caponica/master

Browse Source 
Cleaned up README and edited for readability
This commit is contained in:
Leszek Prabucki 2013-06-17 00:53:15 -07:00
commit 6c615bde72
1 changed files with 108 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
README.markdown
View File

@ -7,7 +7,7 @@ About Gaufrette
--------------- ---------------
Gaufrette is a PHP 5.3+ library providing a filesystem abstraction layer. Gaufrette is a PHP 5.3+ library providing a filesystem abstraction layer.
This abstraction layer permits you to develop your applications without the need to know where all their medias will be stored and how. This abstraction layer allows you to develop applications without needing to know where all their media files will be stored or how.
Documentation is available the [official page of Gaufrette][gaufrette-homepage]. Documentation is available the [official page of Gaufrette][gaufrette-homepage].
@ -36,19 +36,25 @@ you must add the following lines to it:
### Composer Style ### Composer Style
Bundle can be installed using composer by add to require `composer.json` part `"knplabs/knp-gaufrette-bundle": "dev-master"` line. This bundle can be installed using composer by adding the following in the `require` section of your `composer.json` file:
```
"require": {
...
"knplabs/knp-gaufrette-bundle": "dev-master"
},
```
### Git Submodule Style ### Git Submodule Style
If you are versioning your project with git, you had better to embed it If you are versioning your project with git and making changes to this bundle you can embed it as a submodule:
as a submodule:
$ git submodule add https://github.com/KnpLabs/KnpGaufretteBundle.git vendor/bundles/Knp/Bundle/GaufretteBundle $ git submodule add https://github.com/KnpLabs/KnpGaufretteBundle.git vendor/bundles/Knp/Bundle/GaufretteBundle
## Add the namespace in the autoloader ## Add the namespace in the autoloader
You must register both Gaufrette and the KnpGaufretteBundle in your autoloader: You must register both Gaufrette and the KnpGaufretteBundle in your autoloader:
(You do not have to do that if you are using composer autoload system.) (You do not have to do this if you are using the composer autoload system.)
``` php ``` php
<?php <?php
@ -103,7 +109,7 @@ knp_gaufrette:
directory: /path/to/my/filesystem directory: /path/to/my/filesystem
``` ```
The defined adapters are usable to create the filesystems. The defined adapters are then used to create the filesystems.
## Configuring the Filesystems ## Configuring the Filesystems
@ -118,26 +124,26 @@ knp_gaufrette:
alias: foo_filesystem alias: foo_filesystem
``` ```
Each defined filesystem must have an `adapter` with the key of an adapter as value. Each defined filesystem must have an `adapter` with its value set to an adapter's key.
The filesystem defined above with result in a service with id `gaufrette.bar_filesystem`. The filesystem defined above will result in a service with id `gaufrette.bar_filesystem`.
The `alias` parameter permits to also defines an alias for it. The `alias` parameter allows us to define an alias for it (`foo_filesystem` in this case).
The filesystem map The filesystem map
------------------ ------------------
You can access to all declared filesystems through the map service. You can access all declared filesystems through the map service.
In the previous exemple, we declared a `bar` filesystem: In the previous exemple, we declared a `bar` filesystem:
``` php ``` php
$container->get('knp_gaufrette.filesystem_map')->get('bar'); $container->get('knp_gaufrette.filesystem_map')->get('bar');
``` ```
Returns the instance of `Gaufrette\Filesystem` for `bar`. Returns the `bar` instance of `Gaufrette\Filesystem`.
Adapters Reference Adapters Reference
------------------ ------------------
## Local Adapter ## Local Adapter (local)
A simple local filesystem based adapter. A simple local filesystem based adapter.
@ -288,15 +294,13 @@ knp_gaufrette:
hosts: ["192.168.0.1:7001", "192.168.0.2:7001"] hosts: ["192.168.0.1:7001", "192.168.0.2:7001"]
``` ```
[gaufrette-homepage]: https://github.com/KnpLabs/Gaufrette ## Ftp (ftp)
## Ftp
Adapter for FTP. Adapter for FTP.
### Parameters ### Parameters
* `directory` The directory of the filesystem *(required)* * `directory` The remote directory *(required)*
* `host` FTP host *(required)* * `host` FTP host *(required)*
* `username` FTP username *(default null)* * `username` FTP username *(default null)*
* `password` FTP password *(default null)* * `password` FTP password *(default null)*
@ -321,14 +325,14 @@ knp_gaufrette:
mode: FTP_BINARY mode: FTP_BINARY
``` ```
## Sftp ## Sftp (sftp)
Adapter for SFTP (SSH-FTP). Adapter for SFTP (SSH-FTP).
### Parameters ### Parameters
* `sftp_id` The id of the service that provides SFTP access. * `sftp_id` The id of the service that provides SFTP access.
* `directory* The distant directory *(default null)*. * `directory` The remote directory *(default null)*.
* `create` Whether to create the directory if it does not exist *(default false)*. * `create` Whether to create the directory if it does not exist *(default false)*.
### Example ### Example
@ -371,7 +375,7 @@ services:
arguments: [@acme_test.ssh.session] arguments: [@acme_test.ssh.session]
``` ```
## Apc ## Apc (apc)
Adapter for APC. Adapter for APC.
@ -394,6 +398,64 @@ knp_gaufrette:
ttl: 0 ttl: 0
``` ```
## Amazon S3 (amazon_s3)
Adapter to connect to Amazon S3 instances.
This adapter requires the use of amazonwebservices/aws-sdk-for-php which can be installed by adding the following line to your composer.json:
```
"require": {
...
"amazonwebservices/aws-sdk-for-php": "1.6.2"
},
```
Note that Gaufrette is not currently compatible with the v2 Amazon SDK (called "aws/aws-sdk-php").
### Parameters
* `amazon_s3_id`: the id of the AmazonS3 service used for the underlying connection
* `bucket_name`: the name of the bucket to use
* `options`: additional (optional) settings
* `directory`: the directory to use, within the specified bucket
* `region`
* `create`
### Defining services
To use the Amazon S3 adapter you need to provide a valid `AmazonS3` instance (as defined in the Amazon SDK). This can
easily be set up as using Symfony's service configuration:
``` yaml
# app/config/config.yml
services:
amazonS3:
class: AmazonS3
arguments:
options:
key: '%aws_key%'
secret: '%aws_secret_key%'
```
### Example
Once the service is set up use its key as the amazon_s3_id in the gaufrette configuration:
``` yaml
# app/config/config.yml
knp_gaufrette:
adapters:
foo:
amazon_s3:
amazon_s3_id: amazonS3
bucket_name: foo_bucket
options:
directory: foo_directory
```
Note that the SDK seems to have some issues with bucket names with dots in them, e.g. "com.mycompany.bucket" seems to have issues but "com-mycompany-bucket" works.
## Open Cloud (opencloud) ## Open Cloud (opencloud)
Adapter for OpenCloud (Rackspace) Adapter for OpenCloud (Rackspace)
@ -402,14 +464,14 @@ Adapter for OpenCloud (Rackspace)
* `object_store_id`: the id of the object store service * `object_store_id`: the id of the object store service
* `container_name`: the name of the container to use * `container_name`: the name of the container to use
* `create_container`: if `true` will create the container in case it's needed *(default `false`)* * `create_container`: if `true` will create the container if it doesn't exist *(default `false`)*
* `detect_content_type`: if `true` will detect the content type for each file *(default `true`)* * `detect_content_type`: if `true` will detect the content type for each file *(default `true`)*
### Defining services ### Defining services
To use the OpenCloud adapter you should provide a valid `ObjectStore` instance. You can retrieve an instance through the To use the OpenCloud adapter you should provide a valid `ObjectStore` instance. You can retrieve an instance through the
`OpenCloud\OpenStack` or `OpenCloud\Rackspace` instances. We can provide a comprehensive configuration through the Symfony `OpenCloud\OpenStack` or `OpenCloud\Rackspace` instances. We can provide a comprehensive configuration through the Symfony
DiC configuration. DIC configuration.
#### Define OpenStack/Rackspace service #### Define OpenStack/Rackspace service
@ -496,9 +558,9 @@ knp_gaufrette:
container_name: foo container_name: foo
``` ```
## Cache ## Cache (cache)
Adapter which allow to cache other adapters Adapter which allows you to cache other adapters
### Parameters ### Parameters
@ -537,18 +599,20 @@ knp_gaufrette:
## Stream Wrapper ## Stream Wrapper
You can register filesystems with a specified domain. The `stream_wrapper` settings allow you to register filesystems with a specified domain and
And use as a stream wrapper anywhere in your code like : then use as a stream wrapper anywhere in your code like:
`gaufrette://domain/file.txt` `gaufrette://domain/file.txt`
### Parameters ### Parameters
* `protocol` The protocol name like `gaufrette://…` *(default gaufrette)* * `protocol` The protocol name like `gaufrette://…` *(default gaufrette)*
* `filesystem` An array that contains files systems that you want to register with the possibility to set the key of the array * `filesystem` An array that contains filesystems that you want to register to this stream_wrapper.
as the domain like `gaufrette://mydomain/…` *(default all filesystems)* If you set array keys these will be used as an alias for the filesystem (see examples below) *(default all filesystems without aliases)*
### Example 1 ### Example 1
The protocol is gaufrette and all filesystems will be saved
Using default settings, the protocol is "gaufrette" and all filesystems will be served
``` yaml ``` yaml
# app/config/config.yml # app/config/config.yml
knp_gaufrette: knp_gaufrette:
@ -566,12 +630,14 @@ knp_gaufrette:
``` ```
``` ```
gaufrette://backup1/file gaufrette://backup1/...
gaufrette://amazonS3/file gaufrette://amazonS3/...
``` ```
### Example 2 ### Example 2
We define the protocol as data and all filesystem will be saved
We define the protocol as "data", all filesystem will still be served (by default)
``` yaml ``` yaml
# app/config/config.yml # app/config/config.yml
knp_gaufrette: knp_gaufrette:
@ -588,7 +654,9 @@ data://amazonS3/...
``` ```
### Example 3 ### Example 3
We define the protocol as data and define which filesystem will be used
We define the protocol as data and define which filesystem(s) will be available
``` yaml ``` yaml
# app/config/config.yml # app/config/config.yml
knp_gaufrette: knp_gaufrette:
@ -599,15 +667,16 @@ knp_gaufrette:
protocol: data protocol: data
filesystems: filesystems:
- backup1 - backup1
- amazonS3
``` ```
``` ```
data://backup1/... data://backup1/... (works since it is defined above)
data://amazonS3/... data://amazonS3/... (will not be available)
``` ```
### Example 4 ### Example 4
We define the protocol as data and define which filesystem will be used with the domain aliasing
We define the protocol as data and define which filesystems will be available using array keys to set domain aliases
``` yaml ``` yaml
# app/config/config.yml # app/config/config.yml
@ -626,3 +695,5 @@ knp_gaufrette:
data://backup/... data://backup/...
data://pictures/... data://pictures/...
``` ```
[gaufrette-homepage]: https://github.com/KnpLabs/Gaufrette