Skip to content

Commit 4fb6607

Browse files
tgalopintgalopin
committed
Add doc, fix some bugs
1 parent 7133e1f commit 4fb6607

16 files changed

Lines changed: 414 additions & 66 deletions

‎docs/1-getting-started.md‎

Lines changed: 102 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
- [Installation](#installation)
44
- [Basic usage](#basic-usage)
5-
- [Defining multiple filesystems](#defining-multiple-filesystems)
5+
- [Using multiple storages to improve readability](#using-multiple-storages-to-improve-readability)
6+
- [Using memory storage in tests](#using-memory-storage-in-tests)
67

78
## Installation
89

@@ -11,7 +12,7 @@ flysystem-bundle requires PHP 7.1+ and Symfony 4.2+.
1112
You can install the bundle using Symfony Flex:
1213

1314
```
14-
composer require thephpleague/flysystem-bundle
15+
composer require league/flysystem-bundle
1516
```
1617

1718
## Basic usage
@@ -23,90 +24,136 @@ use Flysystem in your application as soon as you install the bundle:
2324
# config/packages/flysystem.yaml
2425

2526
flysystem:
26-
default_filesystem: 'default.storage'
27-
filesystems:
27+
storages:
2828
default.storage:
29-
adapter: 'flysystem.adapter.local'
29+
adapter: 'local'
30+
options:
31+
directory: '%kernel.project_dir%/storage'
3032
```
3133
32-
This configuration creates a single filesystem service, configured using the local adapter in the `storge` directory,
33-
and provides this service for autowiring using the `League\Flysystem\FilesystemInterface` interface.
34-
This autowiring will target the default filesystem defined in the bundle configuration.
35-
36-
This means that if you are using autowiring, you can typehint `League\Flysystem\FilesystemInterface` in any
37-
of your services to get the default filesystem:
34+
This configuration defines a single storage service (`default.storage`) based on the local adapter
35+
and configured to use the `%kernel.project_dir%/storage` directory.
3836

39-
```php
40-
use League\Flysystem\FilesystemInterface;
37+
For each storage defined under `flysystem.storages`, an associated service is created using the
38+
name you provide (in this case, a service `default.storage` will be created). The bundle also
39+
creates a named alias for each of these services.
4140

42-
class MyService
43-
{
44-
private $storage;
41+
This means you have two way of using the defined storages:
42+
43+
* either using autowiring, by typehinting against the `FilesystemInterface` and using the
44+
variable name matching one of your storages:
45+
46+
```php
47+
use League\Flysystem\FilesystemInterface;
4548
46-
public function __construct(FilesystemInterface $storage)
49+
class MyService
4750
{
48-
$this->storage = $storage;
51+
private $storage;
52+
53+
// The variable name $defaultStorage matters: it needs to be the camelized version
54+
// of the name of your storage.
55+
public function __construct(FilesystemInterface $defaultStorage)
56+
{
57+
$this->storage = $defaultStorage;
58+
}
59+
60+
// ...
4961
}
62+
```
5063

51-
// ...
52-
}
53-
```
64+
The same goes for controllers:
65+
66+
```php
67+
use League\Flysystem\FilesystemInterface;
68+
69+
class MyController
70+
{
71+
// The variable name $defaultStorage matters: it needs to be the camelized version
72+
// of the name of your storage.
73+
public function index(FilesystemInterface $defaultStorage)
74+
{
75+
// ...
76+
}
77+
}
78+
```
79+
80+
* or using manual injection, by injecting the service named `default.storage` inside
81+
your services.
82+
83+
84+
## Using multiple storages to improve readability
85+
86+
While using the default storage can be enough, it is usually recommended to create multiple
87+
storages, even if behind the scene you may rely on the same adapter.
88+
89+
The reason for this is the added readability this provides to your project code: by naming
90+
your storages using their **intents**, your will naturally increase the readability of your
91+
autowired arguments. For example:
92+
93+
```yaml
94+
# config/packages/flysystem.yaml
5495
55-
The same goes for controllers:
96+
flysystem:
97+
storages:
98+
users.storage:
99+
adapter: 'local'
100+
options:
101+
directory: '%kernel.project_dir%/storage/users'
102+
103+
projects.storage:
104+
adapter: 'local'
105+
options:
106+
directory: '%kernel.project_dir%/storage/projects'
107+
```
56108

57109
```php
58110
use League\Flysystem\FilesystemInterface;
59111
60-
class MyController
112+
class MyService
61113
{
62-
public function index(FilesystemInterface $storage)
114+
private $usersStorage;
115+
private $projectsStorage;
116+
117+
public function __construct(FilesystemInterface $usersStorage, FilesystemInterface $projectsStorage)
63118
{
64-
// ...
119+
$this->usersStorage = $usersStorage;
120+
$this->projectsStorage = $projectsStorage;
65121
}
122+
123+
// ...
66124
}
67125
```
68126

69-
If you are not using autowiring, you can inject the `flysystem` service into your services
70-
manually to get the default filesystem.
71127

72-
## Defining multiple filesystems
128+
## Using memory storage in tests
73129

74-
Using a single filesystem is good way to get up and running quickly, but it is often useful to
75-
create multiple instances of Flysystem in order to manage different filesystems.
130+
One of the best reason to use a filesystem abstraction in your project is the ability
131+
it gives you to swap the actual implementation during tests.
76132

77-
This bundle provides this ability using `named aliases`: by leveraging the variable name in addition to
78-
the interface name, autowiring is able to inject the proper filesystem you want in your services.
133+
More specifically, it can be useful to swap from a persisted storage to a memory one during
134+
tests, both to ensure the state is reset between tests and to increase tests speed.
79135

80-
This means that if you are using autowiring, you can create multiple filesystems in the configuration of the
81-
bundle and typehint `League\Flysystem\FilesystemInterface` with a variable having the same name as your filesystem
82-
name to get this specific filesystem:
136+
To achieve this, you can overwrite your storages in the test environment:
83137

84138
```yaml
85139
# config/packages/flysystem.yaml
86140
87141
flysystem:
88-
default_filesystem: 'app'
89-
filesystems:
90-
upload.storage:
142+
storages:
143+
users.storage:
91144
adapter: 'local'
92145
options:
93-
directory: '%kernel.project_dir%/storage'
94-
95-
tmp.storage:
96-
adapter: 'flysystem.adapter.local'
97-
options:
98-
directory: '/tmp'
99-
```
146+
directory: '%kernel.project_dir%/storage/users'
147+
```
100148

101-
```php
102-
use League\Flysystem\FilesystemInterface;
149+
```yaml
150+
# config/packages/test/flysystem.yaml
103151
104-
class MyController
105-
{
106-
public function index(FilesystemInterface $fs, FilesystemInterface $tmpStorage)
107-
{
108-
// $fs is referencing the default filesystem ("app") because the variable name is not a filesystem name
109-
// $tmpStorage is referencing the "tmp.storage" filesystem
110-
}
111-
}
152+
flysystem:
153+
storages:
154+
users.storage:
155+
adapter: 'memory'
112156
```
157+
158+
This configuration will swap every reference to the `users.storage` service (or to the
159+
`FilesystemInterface $usersStorage` typehint) from a local adapter to a memory one during tests.

‎docs/2-caching.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/2-cloud-storage-providers.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Cloud storage providers
2+
3+
One of the core feature of Flysystem is its ability to interact easily with remote filesystems,
4+
including many cloud storage providers. This bundle provides the same level of support for these
5+
cloud providers by providing corresponding adapters in the configuration.
6+
7+
## Azure
8+
9+
### Installation
10+
11+
```
12+
composer require league/flysystem-azure-blob-storage
13+
```
14+
15+
### Usage
16+
17+
```yaml
18+
# config/packages/flysystem.yaml
19+
20+
flysystem:
21+
storages:
22+
users.storage:
23+
adapter: 'azure'
24+
options:
25+
client: 'azure_client_service' # The service ID of the MicrosoftAzure\Storage\Blob\BlobRestProxy instance
26+
container: 'container_name'
27+
prefix: 'optional/path/prefix'
28+
```
29+
30+
## AWS
31+
32+
### Installation
33+
34+
```
35+
composer require league/flysystem-aws-s3-v3
36+
```
37+
38+
### Usage
39+
40+
```yaml
41+
# config/packages/flysystem.yaml
42+
43+
flysystem:
44+
storages:
45+
users.storage:
46+
adapter: 'aws'
47+
options:
48+
client: 'aws_client_service' # The service ID of the Aws\S3\S3Client instance
49+
bucket: 'bucket_name'
50+
prefix: 'optional/path/prefix'
51+
```
52+
53+
## DigitalOcean Spaces
54+
55+
The DigitalOcean Spaces are compatible with the AWS S3 API, meaning that you can use the same configuration
56+
as for a AWS storage.
57+
58+
## Scaleway Object Storage
59+
60+
The Scaleway Object Storage is compatible with the AWS S3 API, meaning that you can use the same configuration
61+
as for a AWS storage.
62+
63+
## Dropbox
64+
65+
### Installation
66+
67+
```
68+
composer require spatie/flysystem-dropbox
69+
```
70+
71+
### Usage
72+
73+
```yaml
74+
# config/packages/flysystem.yaml
75+
76+
flysystem:
77+
storages:
78+
users.storage:
79+
adapter: 'dropbox'
80+
options:
81+
client: 'dropbox_client_service' # The service ID of the Spatie\Dropbox\Client instance
82+
prefix: 'optional/path/prefix'
83+
```
84+
85+
## Google Cloud Storage
86+
87+
### Installation
88+
89+
```
90+
composer require superbalist/flysystem-google-storage
91+
```
92+
93+
### Usage
94+
95+
```yaml
96+
# config/packages/flysystem.yaml
97+
98+
flysystem:
99+
storages:
100+
users.storage:
101+
adapter: 'gcloud'
102+
options:
103+
client: 'gcloud_client_service' # The service ID of the Google\Cloud\Storage\StorageClient instance
104+
bucket: 'bucket_name'
105+
prefix: 'optional/path/prefix'
106+
api_url: 'https://storage.googleapis.com'
107+
```
108+
109+
## Rackspace
110+
111+
### Installation
112+
113+
```
114+
composer require league/flysystem-rackspace
115+
```
116+
117+
### Usage
118+
119+
```yaml
120+
# config/packages/flysystem.yaml
121+
122+
flysystem:
123+
storages:
124+
users.storage:
125+
adapter: 'rackspace'
126+
options:
127+
container: 'rackspace_container_service' # The service ID of the OpenCloud\ObjectStore\Resource\Container instance
128+
prefix: 'optional/path/prefix'
129+
```
130+
131+
## WebDAV
132+
133+
### Installation
134+
135+
```
136+
composer require league/flysystem-webdav
137+
```
138+
139+
### Usage
140+
141+
```yaml
142+
# config/packages/flysystem.yaml
143+
144+
flysystem:
145+
storages:
146+
users.storage:
147+
adapter: 'webdav'
148+
options:
149+
client: 'webdav_client_service' # The service ID of the Sabre\DAV\Client instance
150+
prefix: 'optional/path/prefix'
151+
use_stream_copy: false
152+
```

‎docs/3-using-mount-manager.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎src/Adapter/AdapterDefinitionFactory.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ public function __construct()
3636
new Builder\FtpAdapterDefinitionBuilder($this),
3737
new Builder\GcloudAdapterDefinitionBuilder($this),
3838
new Builder\LocalAdapterDefinitionBuilder($this),
39+
new Builder\MemoryAdapterDefinitionBuilder($this),
40+
new Builder\NullAdapterDefinitionBuilder($this),
3941
new Builder\RackspaceAdapterDefinitionBuilder($this),
4042
new Builder\ReplicateAdapterDefinitionBuilder($this),
4143
new Builder\SftpAdapterDefinitionBuilder($this),

0 commit comments

Comments
 (0)