README

An optional fieldset for asynchronous image-upload form data. Built for wilycode/form without adding image-specific code or dependencies to the Form core.

WilyCode PHP Ecosystem

Part of WilyCode — modular, independently released PHP libraries.

Explore the WilyCode PHP Ecosystem →

Installation
Quick start
Fields and validation
Security and responsibilities
API reference
Development
License

Installation

composer require wilycode/form-image-upload

Requires PHP 8.4+. Composer installs wilycode/form, wilycode/filters and wilycode/validators automatically. The core Form library can still be used without this extension.

Quick start

<?php

declare(strict_types=1);

use WilyCode\Form\Form;
use WilyCode\FormImageUpload\ImageUploadFieldset;

final class ProfileForm extends Form
{
    protected function init(): void
    {
        $this->add(new ImageUploadFieldset('avatar'));
        $this->add(new ImageUploadFieldset('cover'));
    }
}

$form = new ProfileForm();
$form->setData([
    'avatar' => [
        'token' => 'temporary-upload-token',
        'existingId' => '',
        'remove' => '0',
        'crop' => ['x' => '10', 'y' => '20', 'width' => '400', 'height' => '400'],
    ],
]);

if ($form->isValid()) {
    $data = $form->getData();
    // Resolve token, authorize resource access, validate uploads and persist data here.
}

You can use ImageUploadFieldset('avatar', required: true) if the entire fieldset must contain a meaningful value.

Fields and validation

Field	Purpose	Built-in behavior
`file`	Submitted upload object	Optional, empty value `null`
`token`	Temporary upload reference	Optional string, max 255 characters; non-empty non-string values rejected
`existingId`	Existing image identifier	Optional string, max 20 characters; non-empty non-string values rejected
`remove`	Remove-existing-image intent	Converted into a boolean via `TypeFilter`
`crop`	Optional crop/transform metadata	Nested `x`, `y`, `width`, `height`, `rotate`, `scaleX`, `scaleY` fields

ImageUploadFieldset::FILE, TOKEN, EXISTING_ID, REMOVE, CROP and CROP_FIELDS are available as constants. The extension stores the submitted form values; it does not process uploaded image files, create thumbnails, store assets or validate image content automatically.

Filter/validator defaults applied by the enclosing form propagate into this fieldset. For example, a TrimFilter added with addDefaultFieldFilter() trims submitted tokens. Since this is a form-data component, you can add custom validators and filters to its fields.

Security and responsibilities

Treat token and existingId as untrusted identifiers. Resolve them server-side and check ownership and permissions.
Empty optional image groups can normalize to [] rather than an array with every child field. Do not assume every child key exists.
remove uses a strict boolean conversion filter: malformed non-boolean-like input may throw InvalidArgumentException while assigning form data. Handle rejected requests at the application boundary.
Enforce file type, true MIME type, size, content validation and storage policy in the consuming application.
Validate and constrain crop coordinates, image dimensions and transformations before using them.
Protect requests with CSRF and authorization checks where applicable.
Never treat a token's presence as proof that an upload has been accepted or persisted.

API reference

API	Meaning
`new ImageUploadFieldset(string $name, bool $required = false)`	Construct a named fieldset.
`ImageUploadFieldset::CROP_FIELDS`	Names of supported crop/transform fields.
`getField('token')`, `getField('remove')`	Access fields for additional rules.
`getFieldset('crop')`	Access crop fields for additional rules.
`setData()`, `getData()`, `isValid()`	Inherited from `wilycode/form`.

The class is WilyCode\FormImageUpload\ImageUploadFieldset, not WilyCode\Form\Fieldsets\ImageUploadFieldset. There is no alias because this is a new, separately published extension.

Development

composer install
composer validate --strict
composer test

GitHub Actions runs PHPUnit on PHP 8.4 and 8.5. Repository tests are omitted from Composer distribution archives.

License

MIT. See LICENSE.

wilycode / form-image-upload

Package info

Security

Statistics