Skip to content

Commit b09cbf8

Browse files
javiereguiluzjaviereguiluz
committed
Doc updates
1 parent d80bad2 commit b09cbf8

File tree

2 files changed

+102
-94
lines changed

2 files changed

+102
-94
lines changed

‎doc/fields/FileField.rst‎

Lines changed: 55 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
EasyAdmin File Field
22
====================
33

4-
This field is used to manage the uploading of files (PDFs, documents, etc.) to
5-
the backend. The entity property only stores the path to the file and not its
6-
binary contents, which are stored in a file.
4+
This field is used to manage the uploading of files (PDFs, documents, etc.) to the
5+
backend. The entity property only stores the path to the file (relative to the
6+
upload directory). The actual file contents are stored on the server filesystem
7+
or on any remote system configured via the `league/flysystem-bundle`_.
78

89
In :ref:`form pages (edit and new) <crud-pages>` it looks like this:
910

@@ -45,9 +46,11 @@ setUploadDir
4546
stored. The argument is the directory relative to your project root::
4647

4748
yield FileField::new('...')->setUploadDir('public/uploads/files/');
49+
// the property will only store the file path relative to this dir
50+
// (e.g. 'catalog.pdf', 'venue/contract.docx')
4851

49-
Unlike ``ImageField``, ``FileField`` does not define a default upload directory.
50-
If you don't call this method, an exception will be thrown.
52+
``FileField`` does not define a default upload directory. If you don't call this
53+
method, an exception will be thrown.
5154

5255
setFileConstraints
5356
~~~~~~~~~~~~~~~~~~
@@ -57,7 +60,7 @@ option to define the constraints applied to the uploaded file::
5760

5861
use Symfony\Component\Validator\Constraints\File;
5962

60-
yield FileField::new('...')->setFileConstraints(new File(maxSize: '2M'));
63+
yield FileField::new('...')->setFileConstraints(new File(filenameCharset: 'ASCII'));
6164

6265
setUploadedFileNamePattern
6366
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,7 +97,8 @@ The string pattern passed as argument can include the following special values:
9497

9598
You can combine them in any way::
9699

97-
yield FileField::new('...')->setUploadedFileNamePattern('[YYYY]/[MM]/[DD]/[slug]-[contenthash].[extension]');
100+
yield FileField::new('...')
101+
->setUploadedFileNamePattern('[YYYY]/[MM]/[DD]/[slug]-[contenthash].[extension]');
98102

99103
The argument of this method also accepts a closure that receives the Symfony's
100104
``UploadedFile`` instance and the **current entity instance** as arguments::
@@ -103,36 +107,38 @@ The argument of this method also accepts a closure that receives the Symfony's
103107
fn (UploadedFile $file): string => sprintf('upload_%d_%s.%s', random_int(1, 999), $file->getFilename(), $file->guessExtension()))
104108
);
105109

106-
Unlike ``ImageField``, the ``FileField`` closure also receives the entity as a
107-
second argument. This allows naming files based on entity data. On the ``new``
108-
page, the entity is a fresh instance (possibly without an ID); on the ``edit``
109-
page, it has its current database values::
110+
The ``FileField`` closure also receives the entity as a second argument. This
111+
allows naming files based on entity data. On the ``new`` page, the entity is a
112+
fresh instance (possibly without an ID); on the ``edit`` page, it has its
113+
current database values::
110114

111115
yield FileField::new('...')->setUploadedFileNamePattern(
112116
static fn (UploadedFile $file, MyEntity $entity): string => sprintf('%s/[name].[extension]', $entity->getSlug()))
113117
);
114118

115-
mimeTypes
116-
~~~~~~~~~
119+
isDeletable
120+
~~~~~~~~~~~
117121

118-
By default, all file types are accepted. Use this option to restrict the allowed
119-
MIME types. The value is a string with a comma-separated list of file extensions
120-
or MIME types. You can use any value valid in the `HTML "accept" attribute`_::
122+
By default, the file upload widget shows a "delete" checkbox that allows users
123+
to remove the uploaded file. Use this option to hide that checkbox::
121124

122-
yield FileField::new('...')->mimeTypes('.pdf,.doc,.docx');
123-
yield FileField::new('...')->mimeTypes('video/*');
124-
yield FileField::new('...')->mimeTypes('image/*');
125-
yield FileField::new('...')->mimeTypes('.doc,.docx,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document');
125+
yield FileField::new('...')->isDeletable(false);
126126

127-
When this option is set, the corresponding MIME types are also added
128-
automatically as validation constraints. You can customize the error message
129-
shown when the validation fails by passing a second argument::
127+
isDownloadable
128+
~~~~~~~~~~~~~~
130129

131-
yield FileField::new('...')->mimeTypes('.pdf', 'The file "{{ name }}" has MIME type "{{ type }}" but only "{{ types }}" are allowed.');
130+
By default, a link to download the uploaded file is displayed next to the form
131+
field. Use this option to hide that link::
132132

133-
The available placeholders for the error message are: ``{{ file }}`` (the absolute
134-
file path), ``{{ name }}`` (the base file name), ``{{ type }}`` (the MIME type of
135-
the uploaded file) and ``{{ types }}`` (the list of allowed MIME types).
133+
yield FileField::new('...')->isDownloadable(false);
134+
135+
isViewable
136+
~~~~~~~~~~
137+
138+
By default, a link to view the uploaded file is displayed next to the form field.
139+
Use this option to hide that link::
140+
141+
yield FileField::new('...')->isViewable(false);
136142

137143
maxSize
138144
~~~~~~~
@@ -153,6 +159,28 @@ file path), ``{{ name }}`` (the base file name), ``{{ size }}`` (the file size),
153159
``{{ limit }}`` (the maximum allowed size) and ``{{ suffix }}`` (the size unit,
154160
e.g. ``kB``, ``MB``).
155161

162+
mimeTypes
163+
~~~~~~~~~
164+
165+
By default, all file types are accepted. Use this option to restrict the allowed
166+
MIME types. The value is a string with a comma-separated list of file extensions
167+
or MIME types. You can use any value valid in the `HTML "accept" attribute`_::
168+
169+
yield FileField::new('...')->mimeTypes('.pdf,.doc,.docx');
170+
yield FileField::new('...')->mimeTypes('video/*');
171+
yield FileField::new('...')->mimeTypes('image/*');
172+
yield FileField::new('...')->mimeTypes('.doc,.docx,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document');
173+
174+
When this option is set, the corresponding MIME types are also added
175+
automatically as validation constraints. You can customize the error message
176+
shown when the validation fails by passing a second argument::
177+
178+
yield FileField::new('...')->mimeTypes('.pdf', 'The file "{{ name }}" has MIME type "{{ type }}" but only "{{ types }}" are allowed.');
179+
180+
The available placeholders for the error message are: ``{{ file }}`` (the absolute
181+
file path), ``{{ name }}`` (the base file name), ``{{ type }}`` (the MIME type of
182+
the uploaded file) and ``{{ types }}`` (the list of allowed MIME types).
183+
156184
Replaced File Behavior
157185
~~~~~~~~~~~~~~~~~~~~~~
158186

@@ -178,30 +206,6 @@ controls what happens to the old file on disk. There are three behaviors:
178206

179207
yield FileField::new('...')->keepReplacedFileOrFail();
180208

181-
isViewable
182-
~~~~~~~~~~
183-
184-
By default, a link to view the uploaded file is displayed next to the form field.
185-
Use this option to hide that link::
186-
187-
yield FileField::new('...')->isViewable(false);
188-
189-
isDownloadable
190-
~~~~~~~~~~~~~~
191-
192-
By default, a link to download the uploaded file is displayed next to the form
193-
field. Use this option to hide that link::
194-
195-
yield FileField::new('...')->isDownloadable(false);
196-
197-
isDeletable
198-
~~~~~~~~~~~
199-
200-
By default, the file upload widget shows a "delete" checkbox that allows users
201-
to remove the uploaded file. Use this option to hide that checkbox::
202-
203-
yield FileField::new('...')->isDeletable(false);
204-
205209
Flysystem Integration (Remote Storage)
206210
--------------------------------------
207211

‎doc/fields/ImageField.rst‎

Lines changed: 47 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@ EasyAdmin Image Field
22
=====================
33

44
This field is used to manage the uploading of images to the backend. The entity
5-
property only stores the path to the image and not its binary contents, which
6-
are stored in a file.
5+
property only stores the path to the image (relative to the upload directory).
6+
The actual image contents are stored on the server filesystem or on any remote
7+
system configured via the `league/flysystem-bundle`_.
78

89
In :ref:`form pages (edit and new) <crud-pages>` it looks like this:
910

@@ -44,6 +45,8 @@ By default, the contents of uploaded images are stored into files inside the
4445
change that location. The argument is the directory relative to your project root::
4546

4647
yield ImageField::new('...')->setUploadDir('assets/images/');
48+
// the property will only store the file path relative to this dir
49+
// (e.g. 'logo.png', 'venue/layout.jpg')
4750

4851
setFileConstraints
4952
~~~~~~~~~~~~~~~~~~
@@ -52,7 +55,7 @@ By default, the uploaded file is validated using an empty `Image constraint`_
5255
(which means it only validates that the uploaded file is of type image). Use this
5356
option to define the constraints applied to the uploaded file::
5457

55-
yield ImageField::new('...')->setFileConstraints(new Image(maxSize: '100k'));
58+
yield ImageField::new('...')->setFileConstraints(new Image(filenameCharset: 'ASCII'));
5659

5760
setUploadedFileNamePattern
5861
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,7 +97,8 @@ The string pattern passed as argument can include the following special values:
9497

9598
You can combine them in any way::
9699

97-
yield ImageField::new('...')->setUploadedFileNamePattern('[YYYY]/[MM]/[DD]/[slug]-[contenthash].[extension]');
100+
yield ImageField::new('...')
101+
->setUploadedFileNamePattern('[YYYY]/[MM]/[DD]/[slug]-[contenthash].[extension]');
98102

99103
The argument of this method also accepts a closure that receives as its first
100104
argument the Symfony's UploadedFile instance::
@@ -103,26 +107,29 @@ argument the Symfony's UploadedFile instance::
103107
fn (UploadedFile $file): string => sprintf('upload_%d_%s.%s', random_int(1, 999), $file->getFilename(), $file->guessExtension()))
104108
);
105109

106-
mimeTypes
107-
~~~~~~~~~
110+
isDeletable
111+
~~~~~~~~~~~
108112

109-
By default, the accepted MIME types are set to ``image/*``, which restricts the
110-
browser's file dialog to image files. Use this option to customize the accepted
111-
file types. The value is a string with a comma-separated list of file extensions
112-
or MIME types. You can use any value valid in the `HTML "accept" attribute`_::
113+
By default, the image upload widget shows a "delete" checkbox that allows users
114+
to remove the uploaded image. Use this option to hide that checkbox::
113115

114-
yield ImageField::new('...')->mimeTypes('.png,.jpg,.webp');
115-
yield ImageField::new('...')->mimeTypes('image/png,image/jpeg');
116+
yield ImageField::new('...')->isDeletable(false);
116117

117-
When this option is set, the corresponding MIME types are also added
118-
automatically as validation constraints. You can customize the error message
119-
shown when the validation fails by passing a second argument::
118+
isDownloadable
119+
~~~~~~~~~~~~~~
120120

121-
yield ImageField::new('...')->mimeTypes('.png,.jpg', 'The image "{{ name }}" has MIME type "{{ type }}" but only "{{ types }}" are allowed.');
121+
By default, a link to download the uploaded image is displayed next to the form
122+
field. Use this option to hide that link::
122123

123-
The available placeholders for the error message are: ``{{ file }}`` (the absolute
124-
file path), ``{{ name }}`` (the base file name), ``{{ type }}`` (the MIME type of
125-
the uploaded file) and ``{{ types }}`` (the list of allowed MIME types).
124+
yield ImageField::new('...')->isDownloadable(false);
125+
126+
isViewable
127+
~~~~~~~~~~
128+
129+
By default, a link to view the uploaded image is displayed next to the form field.
130+
Use this option to hide that link::
131+
132+
yield ImageField::new('...')->isViewable(false);
126133

127134
maxSize
128135
~~~~~~~
@@ -143,6 +150,27 @@ file path), ``{{ name }}`` (the base file name), ``{{ size }}`` (the file size),
143150
``{{ limit }}`` (the maximum allowed size) and ``{{ suffix }}`` (the size unit,
144151
e.g. ``kB``, ``MB``).
145152

153+
mimeTypes
154+
~~~~~~~~~
155+
156+
By default, the accepted MIME types are set to ``image/*``, which restricts the
157+
browser's file dialog to image files. Use this option to customize the accepted
158+
file types. The value is a string with a comma-separated list of file extensions
159+
or MIME types. You can use any value valid in the `HTML "accept" attribute`_::
160+
161+
yield ImageField::new('...')->mimeTypes('.png,.jpg,.webp');
162+
yield ImageField::new('...')->mimeTypes('image/png,image/jpeg');
163+
164+
When this option is set, the corresponding MIME types are also added
165+
automatically as validation constraints. You can customize the error message
166+
shown when the validation fails by passing a second argument::
167+
168+
yield ImageField::new('...')->mimeTypes('.png,.jpg', 'The image "{{ name }}" has MIME type "{{ type }}" but only "{{ types }}" are allowed.');
169+
170+
The available placeholders for the error message are: ``{{ file }}`` (the absolute
171+
file path), ``{{ name }}`` (the base file name), ``{{ type }}`` (the MIME type of
172+
the uploaded file) and ``{{ types }}`` (the list of allowed MIME types).
173+
146174
Replaced File Behavior
147175
~~~~~~~~~~~~~~~~~~~~~~
148176

@@ -168,30 +196,6 @@ controls what happens to the old file on disk. There are three behaviors:
168196

169197
yield ImageField::new('...')->keepReplacedFileOrFail();
170198

171-
isViewable
172-
~~~~~~~~~~
173-
174-
By default, a link to view the uploaded image is displayed next to the form field.
175-
Use this option to hide that link::
176-
177-
yield ImageField::new('...')->isViewable(false);
178-
179-
isDownloadable
180-
~~~~~~~~~~~~~~
181-
182-
By default, a link to download the uploaded image is displayed next to the form
183-
field. Use this option to hide that link::
184-
185-
yield ImageField::new('...')->isDownloadable(false);
186-
187-
isDeletable
188-
~~~~~~~~~~~
189-
190-
By default, the image upload widget shows a "delete" checkbox that allows users
191-
to remove the uploaded image. Use this option to hide that checkbox::
192-
193-
yield ImageField::new('...')->isDeletable(false);
194-
195199
Flysystem Integration (Remote Storage)
196200
--------------------------------------
197201

0 commit comments

Comments
 (0)