KnpGaufretteBundle/README.markdown

435 lines
10 KiB
Markdown
Raw Normal View History

2011-05-08 21:04:37 +00:00
Gaufrette Bundle
================
Provides a [Gaufrette][gaufrette-homepage] integration for your Symfony projects.
2011-05-13 15:49:11 +00:00
About Gaufrette
---------------
Gaufrette is a PHP 5.3+ library providing a filesystem abstraction layer.
2011-12-21 15:48:37 +00:00
This abstraction layer permits you to develop your applications without the need to know where all their medias will be stored and how.
2011-05-13 15:49:11 +00:00
Documentation is available the [official page of Gaufrette][gaufrette-homepage].
2011-05-08 21:04:37 +00:00
Installation
------------
2011-06-18 18:49:55 +00:00
## Prerequisites
2011-05-08 21:04:37 +00:00
As this bundle is an integration for Symfony of the [Gaufrette][gaufrette-homepage] library, it requires you to first install [Gaufrette][gaufrette-homepage] in a Symfony project.
## Download the bundle
You can download an archive of the bundle and unpack it in the `vendor/bundles/Knp/Bundle/GaufretteBundle` directory of your application.
2011-05-08 21:04:37 +00:00
2011-10-03 06:51:48 +00:00
### Standard Edition Style
If you are using the `deps` file to manage your project's dependencies,
you must add the following lines to it:
[gaufrette]
2011-12-03 15:26:18 +00:00
git=http://github.com/KnpLabs/Gaufrette.git
2011-10-03 06:51:48 +00:00
[KnpGaufretteBundle]
2011-12-03 15:26:18 +00:00
git=http://github.com/KnpLabs/KnpGaufretteBundle.git
target=/bundles/Knp/Bundle/GaufretteBundle
2011-10-03 06:51:48 +00:00
### Composer Style
Bundle can be installed using composer by add to require `composer.json` part `"knplabs/knp-gaufrette-bundle": "dev-master"` line.
2011-10-03 06:51:48 +00:00
### Git Submodule Style
If you are versioning your project with git, you had better to embed it
as a submodule:
2011-05-08 21:04:37 +00:00
2011-12-03 15:26:18 +00:00
$ git submodule add https://github.com/KnpLabs/KnpGaufretteBundle.git vendor/bundles/Knp/Bundle/GaufretteBundle
2011-05-08 21:04:37 +00:00
## Add the namespace in the autoloader
2011-05-08 21:04:37 +00:00
2011-10-03 07:02:13 +00:00
You must register both Gaufrette and the KnpGaufretteBundle in your autoloader:
2012-09-05 19:13:18 +00:00
(You do not have to do that if you are using composer autoload system.)
2011-05-08 21:04:37 +00:00
``` php
<?php
// app/autoload.php
$loader->registerNamespaces(array(
2011-10-03 06:51:48 +00:00
'Knp\Bundle' => __DIR__.'/../vendor/bundles',
'Gaufrette' => __DIR__.'/../vendor/gaufrette/src',
2011-05-08 21:04:37 +00:00
// ...
));
```
## Register the bundle
You must register the bundle in your kernel:
``` php
<?php
// app/AppKernel.php
public function registerBundles()
{
$bundles = array(
// ...
new Knp\Bundle\GaufretteBundle\KnpGaufretteBundle()
2011-05-08 21:04:37 +00:00
);
// ...
}
```
Configuration
-------------
The Gaufrette bundle allows you to declare your filesystems as services without having to reach into the famous "Service Container".
Indeed, you can do it with the configuration!
The configuration of the Gaufrette bundle is divided into two parts: the `adapters` and the `filesystems`.
## Configuring the Adapters
``` yaml
# app/config/config.yml
knp_gaufrette:
2011-05-08 21:04:37 +00:00
adapters:
foo:
local:
directory: /path/to/my/filesystem
```
The defined adapters are usable to create the filesystems.
## Configuring the Filesystems
``` yaml
# app/config/config.yml
knp_gaufrette:
2011-05-08 21:04:37 +00:00
adapters:
# ...
filesystems:
bar:
adapter: foo
alias: foo_filesystem
```
Each defined filesystem must have an `adapter` with the key of an adapter as value.
2011-05-13 04:53:07 +00:00
The filesystem defined above with result in a service with id `gaufrette.bar_filesystem`.
2011-05-08 21:04:37 +00:00
The `alias` parameter permits to also defines an alias for it.
2011-06-18 18:49:55 +00:00
The filesystem map
------------------
You can access to all declared filesystems through the map service.
In the previous exemple, we declared a `bar` filesystem:
``` php
$container->get('knp_gaufrette.filesystem_map')->get('bar');
2011-06-18 18:49:55 +00:00
```
Returns the instance of `Gaufrette\Filesystem` for `bar`.
2011-05-08 21:04:37 +00:00
Adapters Reference
------------------
## Local Adapter
A simple local filesystem based adapter.
### Parameters
* `directory` The directory of the filesystem *(required)*
* `create` Whether to create the directory if it does not exist *(default true)*
2011-10-03 13:11:44 +00:00
### Example
2011-05-08 21:04:37 +00:00
``` yaml
# app/config/config.yml
knp_gaufrette:
2011-05-08 21:04:37 +00:00
adapters:
foo:
local:
directory: /path/to/my/filesystem
create: true
```
## Safe Local Adapter (safe\_local)
Almost as simple as the **local** adapter, but it encodes key to avoid having to deal with the directories structure.
### Parameters
* `directory` The directory of the filesystem *(required)*
* `create` Whether to create the directory if it does not exist *(default true)*
2011-10-03 13:11:44 +00:00
### Example
2011-05-08 21:04:37 +00:00
``` yaml
2011-05-13 15:49:11 +00:00
# app/config/config.yml
knp_gaufrette:
2011-05-13 15:49:11 +00:00
adapters:
foo:
safe_local:
directory: /path/to/my/filesystem
create: true
2011-05-08 21:04:37 +00:00
```
## Service (service)
Allows you to use a user defined adapter service.
### Parameters
* `id` The id of the service *(required)*
2011-10-03 13:11:44 +00:00
### Example
2011-05-08 21:04:37 +00:00
``` yaml
2011-05-13 15:49:11 +00:00
# app/config/config.yml
knp_gaufrette:
2011-05-13 15:49:11 +00:00
adapters:
foo:
service:
id: my.adapter.service
2011-05-08 21:04:37 +00:00
```
## In Memory (in\_memory)
Adapter for test purposes, it stores files in an internal array.
### Parameters
* `files` An array of files *(optional)*
The `files` is an array of files where each file is a sub-array having the `content`, `checksum` and `mtime` optional keys.
2011-10-03 13:11:44 +00:00
### Example
2011-05-08 21:04:37 +00:00
``` yaml
2011-05-13 15:49:11 +00:00
# app/config/config.yml
knp_gaufrette:
2011-05-13 15:49:11 +00:00
adapters:
foo:
in_memory:
files:
'file1.txt': ~
'file2.txt':
content: Some content
checksum: abc1efg2hij3
mtime: 123456890123
2011-05-08 21:04:37 +00:00
```
2011-05-13 04:53:07 +00:00
2011-10-03 13:11:44 +00:00
## GridFS (gridfs)
2011-10-12 06:26:48 +00:00
Adapter that allows you to use a MongoDB GridFS for storing files.
2011-10-03 13:11:44 +00:00
### Parameters
* `mongogridfs_id` The id of the service that provides MongoGridFS object instance for adapter *(required)*
### Example
``` yaml
# app/config/config.yml
knp_gaufrette:
adapters:
foo:
gridfs:
mongogridfs_id: acme_test.gridfs
```
In your AcmeTestBundle, add following service definitions:
``` yaml
2011-10-03 13:19:08 +00:00
# src/Acme/TestBundle/Resources/config/services.yml
2011-10-03 13:11:44 +00:00
parameters:
acme_test.mongo.server: "mongodb://localhost:27017"
acme_test.mongo.options:
connect: true
acme_test.mongodb.name: "test_database"
acme_test.gridfs.prefix: "fs" #Default
services:
acme_test.mongo:
class: Mongo
arguments: [%acme_test.mongo.server%, %acme_test.mongo.options%]
acme_test.mongodb:
class: MongoDB
arguments: [@acme_test.mongo, %acme_test.mongodb.name%]
acme_test.gridfs:
class: MongoGridFS
arguments: [@acme_test.mongodb, %acme_test.gridfs.prefix%]
```
2011-10-12 06:47:11 +00:00
Note that it is possible to prepare MongoGridFS service anyway you like. This is just one way to do it.
2011-10-12 06:40:44 +00:00
2011-10-11 12:29:12 +00:00
## MogileFS (mogilefs)
2011-10-12 06:26:48 +00:00
Adapter that allows you to use MogileFS for storing files.
2011-10-11 12:29:12 +00:00
### Parameters
* `domain` MogileFS domain
* `hosts` Available trackers
### Example
``` yaml
# app/config/config.yml
knp_gaufrette:
adapters:
foo:
mogilefs:
domain: foobar
hosts: ["192.168.0.1:7001", "192.168.0.2:7001"]
```
2011-10-03 13:11:44 +00:00
2011-12-03 15:26:18 +00:00
[gaufrette-homepage]: https://github.com/KnpLabs/Gaufrette
## Ftp
Adapter for FTP.
### Parameters
* `directory` The directory of the filesystem *(required)*
* `host` FTP host *(required)*
* `username` FTP username *(default null)*
* `password` FTP password *(default null)*
* `port` FTP port *(default 21)*
* `passive` FTP passive mode *(default false)*
* `create` Whether to create the directory if it does not exist *(default false)*
* `mode` FTP transfer mode *(defaut FTP_ASCII)*
### Example
``` yaml
# app/config/config.yml
knp_gaufrette:
adapters:
foo:
ftp:
host: example.com
username: user
password: pass
directory: /example/ftp
create: true
mode: FTP_BINARY
```
2011-12-12 21:25:17 +00:00
2012-06-06 16:10:09 +00:00
## Sftp
Adapter for SFTP (SSH-FTP).
### Parameters
* `sftp_id` The id of the service that provides SFTP access.
* `directory* The distant directory *(default null)*.
* `create` Whether to create the directory if it does not exist *(default false)*.
### Example
``` yaml
# app/config/config.yml
knp_gaufrette:
adapters:
foo:
sftp:
sftp_id: acme_test.sftp
directory: /example/sftp
create: true
```
In your AcmeTestBundle, add following service definitions:
``` yaml
# src/Acme/TestBundle/Resources/config/services.yml
parameters:
acme_test.ssh.host: my_host_name
acme_test.ssh.username: user_name
acme_test.ssh.password: some_secret
services:
acme_test.ssh.configuration:
class: Ssh\Configuration
arguments: [%acme_test.ssh.host%]
acme_test.ssh.authentication:
class: Ssh\Authentication\Password
arguments: [%acme_test.ssh.username%, %acme_test.ssh.password%]
acme_test.ssh.session:
class: Ssh\Session
arguments: [@acme_test.ssh.configuration, @acme_test.ssh.authentication]
acme_test.sftp:
class: Ssh\Sftp
arguments: [@acme_test.ssh.session]
```
2011-12-12 21:25:17 +00:00
## Apc
Adapter for APC.
A non-persistent adapter, use it in the dev environment, in demo sites, ...
### Parameters
* `prefix` The prefix to this filesystem (APC 'namespace', it is recommended that this end in a dot '.') *(required)*
* `ttl` Time to live *(default 0)*
### Example
``` yaml
# app/config/config.yml
knp_gaufrette:
adapters:
foo:
apc:
prefix: APC 'namespace' prefix
ttl: 0
```
## Cache
Adapter which allow to cache other adapters
### Parameters
* `source` The source adapter that must be cached *(required)*
* `cache` The adapter used to cache the source *(required)*
* `ttl` Time to live *(default 0)*
* `serializer` The adapter used to cache serializations *(default null)*
### Example
``` yaml
# app/config/config.yml
knp_gaufrette:
adapters:
media_ftp:
ftp:
host: example.com
username: user
password: pass
directory: /example/ftp
create: true
mode: FTP_BINARY
media_apc:
apc:
prefix: APC 'namespace' prefix
ttl: 0
media_cache:
cache:
source: media_ftp
cache: media_apc
ttl: 7200
filesystems:
media:
adapter: media_cache
```