From 744a0b63c08daa71d059fedc15000ebbba7dbc45 Mon Sep 17 00:00:00 2001 From: Christian Morgan Date: Fri, 14 Jun 2013 14:49:25 +0200 Subject: [PATCH 1/2] Cleaned up README and edited for readability --- README.markdown | 87 ++++++++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 37 deletions(-) diff --git a/README.markdown b/README.markdown index 2d52bda..8049466 100644 --- a/README.markdown +++ b/README.markdown @@ -7,7 +7,7 @@ About Gaufrette --------------- 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]. @@ -36,19 +36,25 @@ you must add the following lines to it: ### 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 -If you are versioning your project with git, you had better to embed it -as a submodule: +If you are versioning your project with git and making changes to this bundle you can embed it as a submodule: $ git submodule add https://github.com/KnpLabs/KnpGaufretteBundle.git vendor/bundles/Knp/Bundle/GaufretteBundle ## Add the namespace in the 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 get('knp_gaufrette.filesystem_map')->get('bar'); ``` -Returns the instance of `Gaufrette\Filesystem` for `bar`. +Returns the `bar` instance of `Gaufrette\Filesystem`. Adapters Reference ------------------ -## Local Adapter +## Local Adapter (local) A simple local filesystem based adapter. @@ -265,7 +271,7 @@ services: arguments: [@acme_test.mongodb, %acme_test.gridfs.prefix%] ``` -Note that it is possible to prepare MongoGridFS service anyway you like. This is just one way to do it. +Note that it is possible to prepare MongoGridFS service any way you like. This is just one way to do it. ## MogileFS (mogilefs) @@ -288,15 +294,13 @@ knp_gaufrette: hosts: ["192.168.0.1:7001", "192.168.0.2:7001"] ``` -[gaufrette-homepage]: https://github.com/KnpLabs/Gaufrette - -## Ftp +## Ftp (ftp) Adapter for FTP. ### Parameters - * `directory` The directory of the filesystem *(required)* + * `directory` The remote directory *(required)* * `host` FTP host *(required)* * `username` FTP username *(default null)* * `password` FTP password *(default null)* @@ -321,14 +325,14 @@ knp_gaufrette: mode: FTP_BINARY ``` -## Sftp +## Sftp (sftp) Adapter for SFTP (SSH-FTP). ### Parameters * `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)*. ### Example @@ -371,7 +375,7 @@ services: arguments: [@acme_test.ssh.session] ``` -## Apc +## Apc (apc) Adapter for APC. @@ -402,14 +406,14 @@ Adapter for OpenCloud (Rackspace) * `object_store_id`: the id of the object store service * `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`)* ### Defining services 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 -DiC configuration. +DIC configuration. #### Define OpenStack/Rackspace service @@ -496,9 +500,9 @@ knp_gaufrette: container_name: foo ``` -## Cache +## Cache (cache) -Adapter which allow to cache other adapters +Adapter which allows you to cache other adapters ### Parameters @@ -537,18 +541,20 @@ knp_gaufrette: ## Stream Wrapper -You can register filesystems with a specified domain. -And use as a stream wrapper anywhere in your code like : +The `stream_wrapper` settings allow you to register filesystems with a specified domain and +then use as a stream wrapper anywhere in your code like: `gaufrette://domain/file.txt` ### Parameters * `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 - as the domain like `gaufrette://mydomain/…` *(default all filesystems)* + * `filesystem` An array that contains filesystems that you want to register to this stream_wrapper. + 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 -The protocol is gaufrette and all filesystems will be saved + +Using default settings, the protocol is "gaufrette" and all filesystems will be served + ``` yaml # app/config/config.yml knp_gaufrette: @@ -566,12 +572,14 @@ knp_gaufrette: ``` ``` -gaufrette://backup1/file -gaufrette://amazonS3/file +gaufrette://backup1/... +gaufrette://amazonS3/... ``` ### 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 # app/config/config.yml knp_gaufrette: @@ -588,7 +596,9 @@ data://amazonS3/... ``` ### 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 # app/config/config.yml knp_gaufrette: @@ -599,15 +609,16 @@ knp_gaufrette: protocol: data filesystems: - backup1 - - amazonS3 ``` ``` -data://backup1/... -data://amazonS3/... +data://backup1/... (works since it is defined above) +data://amazonS3/... (will not be available) ``` + ### 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 # app/config/config.yml @@ -626,3 +637,5 @@ knp_gaufrette: data://backup/... data://pictures/... ``` + +[gaufrette-homepage]: https://github.com/KnpLabs/Gaufrette From da1b5f97501d91321009c51cb11f034ebdfb002b Mon Sep 17 00:00:00 2001 From: Christian Morgan Date: Fri, 14 Jun 2013 22:18:40 +0200 Subject: [PATCH 2/2] Added documentation for amazon_s3 adapter I've added what I understand based on getting this working today. Not sure about all the options. I also added a note about bucket names with dots in them - this had me stuck for a while until I found mention of it in passing in an AWS ticket https://forums.aws.amazon.com/thread.jspa?threadID=122890#jive-message-445833 If it's not a generally repeatable problem feel free to delete that line, but it certainly caused me problems! --- README.markdown | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/README.markdown b/README.markdown index 8049466..0663422 100644 --- a/README.markdown +++ b/README.markdown @@ -398,6 +398,64 @@ knp_gaufrette: 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) Adapter for OpenCloud (Rackspace)