---
title: "Exceptions and Translations"
description: "Catch typed value failures, preserve their causes and translate package exceptions"
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-10-26"
last_update: "2026-10-26"
time_minutes: 2
draft: false
unlisted: false
url: "https://www.derafu.dev/docs/data/value/translations"
---

# Exceptions and Translations

All package exceptions are translatable and can be caught as PHP's `InvalidArgumentException`.

| Exception in Derafu\Value\Exception | Parent | Cause |
| --- | --- | --- |
| `ValueException` | `TranslatableInvalidArgumentException` | Invalid value-type definitions, such as a non-backed enum class. |
| `TypeMismatchException` | `ValueException` | A value does not match a ValueType definition or a strict ValueCaster read. |
| `ValueConversionException` | `TranslatableInvalidArgumentException` | A requested scalar conversion fails. |

`ValueConversionException` is separate from `ValueException`. Catch the specific classes or their common `TranslatableInvalidArgumentException` parent when handling both categories.

Strict `ValueCaster::getXXX()` / `requireXXX()` methods reuse ValueType validation and raise TypeMismatchException for rejected input. If a Stringable read fails during conversion, the cause chain contains ValueConversionException followed by the original throwable. `ValueType::string()` itself still accepts PHP strings only.

## Conversion Failures

```php
use Derafu\Value\Exception\ValueConversionException;
use Derafu\Value\ValueCaster;

try {
    ValueCaster::toInt('text');
} catch (ValueConversionException $exception) {
    echo $exception->getMessage();
    // A value of type string cannot be converted to int.
}
```

`toNumber()` propagates the exception from its final `toFloat()` attempt if both conversions fail. A failing Stringable conversion is wrapped with the original throwable available through `getPrevious()`.

## Type Failures and Causes

```php
use Derafu\Value\Exception\TypeMismatchException;
use Derafu\Value\ValueType;

try {
    ValueType::toInt()->parse('text', 'quantity', 'settings.php');
} catch (TypeMismatchException $exception) {
    echo $exception->getMessage();
    // The value at "quantity" of settings.php must be of type int, string given.

    $cause = $exception->getPrevious(); // ValueConversionException
}
```

Conversion types wrap ValueConversionException as TypeMismatchException to add location and source context, retaining the original cause. Strict type mismatches do not need an underlying conversion failure. A missing path is displayed as `$`; a source is included only when one is supplied.

## Spanish Translations

The package supplies `resources/translations/errors+intl-icu.es.php` through `Derafu\Value\Translation\ValueTranslationResourceProvider`. The provider supplies resources; an application creates and configures its translator.

```php
use Derafu\Translation\TranslatorFactory;
use Derafu\Value\Exception\ValueConversionException;
use Derafu\Value\Translation\ValueTranslationResourceProvider;
use Derafu\Value\ValueCaster;

$translator = TranslatorFactory::create(
    defaultLocale: 'es',
    fallbackLocales: ['es', 'en'],
    resourceProviders: [new ValueTranslationResourceProvider()],
);

try {
    ValueCaster::toInt('text');
} catch (ValueConversionException $exception) {
    echo $exception->trans($translator);
    // Un valor de tipo string no se puede convertir a int.
}
```

## Dependency Injection

Applications using Symfony DependencyInjection can import the optional recipe:

```yaml
imports:
    - { resource: '../vendor/derafu/value/resources/config/value-services.yaml' }
```

It tags `ValueTranslationResourceProvider` with `derafu_translation.resource_provider`. Pass providers with that tag to `TranslatorFactory::create()` through `$resourceProviders`, following [Derafu Translation](https://www.derafu.dev/docs/core/translation). Symfony DependencyInjection is not a runtime requirement of the value utilities.



---
Last updated on 26/10/2026