Skip to content

Kirby 5.6.1

    Search by Algolia

    $file

    The $file object provides a set of methods that can be used when dealing with a single image or other media file, like getting the URL or resizing an image. It also handles file meta data.

    You can extend this set of methods with custom file methods.

    How to get a $file object

    You can get a $file object to use with these methods by fetching it from the $site, a $page or a $user object.

    Site file

    <?php if ($file = $site->files()->first()): ?>
<img src="<?= $file->url() ?>" alt="">
<?php endif ?>

    Page file

    <?php if ($file = $page->files()->first()): ?>
<img src="<?= $file->url() ?>" alt="">
<?php endif ?>

    User file

    <?php if ($file = $user->files()->first()): ?>
<img src="<?= $file->url() ?>" alt="">
<?php endif ?>

    Note how we use an if statement here to check if we have a file object before we call the url() method to prevent errors in case the page doesn't have any files. Never forget to do this in your own code.

    Content fields

    The $file class offers a magic caller for your content fields. Instead of getting them via $file->content()->get('your_field'), you can use the shorthand $file->your_field().

    Reserved names

    You cannot use the shorthand for fields with names that conflict with methods of the $file class or with custom file methods. Besides the methods listed above, this also includes internal methods that are not part of the documented API. The following names are reserved:

    apiUrl, asset, base64, blueprint, blueprints, blur, bw, changeName, changeSort, changeStorage, changeTemplate, clone, content, contentFileData, copy, create, createContent, createDefaultContent, createTranslations, crop, dataUri, decrement, delete, dimensions, download, errors, exif, exists, extension, factory, filename, files, getMethod, grayscale, greyscale, hardcopy, hash, hasMethod, hasNext, hasPrev, header, height, html, id, imagesize, increment, indexOf, is, isAccessible, isFirst, isLandscape, isLast, isListable, isLocked, isNth, isPortrait, isReadable, isResizable, isSquare, isValid, isViewable, isWritable, kirby, lock, manipulate, match, mediaDir, mediaHash, mediaRoot, mediaToken, mediaUrl, mime, model, modified, move, name, next, nextAll, niceSize, orientation, page, panel, parent, parentId, parents, permalink, permissions, prev, prevAll, previewUrl, publish, purge, quality, query, ratio, read, readContent, realpath, rename, replace, resize, root, sanitizeContents, save, sha1, sharpen, siblings, site, size, srcset, storage, template, templateSiblings, thumb, toArray, toJson, toSafeString, toString, translation, translations, type, unpublish, update, url, uuid, validateContents, version, versions, width, write, writeContent

    To access a field with a reserved name, use $file->content()->get('fieldname'). We recommend prefixing your field names instead to avoid any conflicts.

    Examples

    Resizing a file

    <?php if ($image = $page->image('myimage.jpg')): ?>
<img src="<?= $image->resize(300)->url() ?>" alt="">
<?php endif ?>