coroq/form-lang-ja

v1.0.0 2025-11-21 15:13 UTC

Requires

• php: ^8.0
• coroq/form: ^3.0

Requires (Dev)

• phpunit/phpunit: ^9.6

MIT

• Ozawa Masayuki

README

Japanese language extension for coroq/form. Provides Japanese-specific form inputs with automatic character conversion and validation.

Features

• KatakanaInput - Validates katakana characters only
• HiraganaInput - Validates hiragana characters only
• BasicErrorMessages - Japanese error messages for all form errors

Installation

composer require coroq/form-lang-ja

Requires:

• PHP ^8.0
• coroq/form ^3.0

Quick Start

use Coroq\Form\Form;
use Coroq\Form\Lang\Ja\FormItem\KatakanaInput;
use Coroq\Form\Lang\Ja\FormItem\HiraganaInput;

class NameForm extends Form {
    public readonly KatakanaInput $nameKana;
    public readonly HiraganaInput $nameHiragana;

    public function __construct() {
        $this->nameKana = new KatakanaInput();
        $this->nameHiragana = new HiraganaInput();
    }
}

$form = new NameForm();
$form->setValue([
    'nameKana' => 'やまだ たろう',      // Hiragana input
    'nameHiragana' => 'ヤマダ タロウ'   // Katakana input
]);

if ($form->validate()) {
    echo $form->nameKana->getValue();      // "ヤマダ　タロウ" (converted to katakana)
    echo $form->nameHiragana->getValue();  // "やまだ　たろう" (converted to hiragana)
}

KatakanaInput

Automatically converts input to katakana and validates that the result contains only katakana characters.

use Coroq\Form\Form;
use Coroq\Form\Lang\Ja\FormItem\KatakanaInput;

class UserForm extends Form {
    public readonly KatakanaInput $furigana;

    public function __construct() {
        $this->furigana = (new KatakanaInput())
            ->setLabel('フリガナ')
            ->setMaxLength(50);
    }
}

$form = new UserForm();

// Automatic conversion to katakana
$form->furigana->setValue('やまだたろう');  // Hiragana
echo $form->furigana->getValue();  // "ヤマダタロウ" (katakana)

$form->furigana->setValue('ﾔﾏﾀﾞﾀﾛｳ');     // Half-width
echo $form->furigana->getValue();  // "ヤマダタロウ" (full-width)

// Validation
$form->furigana->setValue('山田太郎');  // Kanji
$form->validate();  // false - NotKatakanaError

$form->furigana->setValue('ABC123');   // Alphabet/numbers
$form->validate();  // false - NotKatakanaError

Accepted Characters

• Katakana: ァ-ヴ
• Long dash: ー (used in コーヒー, タクシー)
• Combining marks: ゙゚ (for Unicode normalization)

Type-Safe Access

// Returns validated katakana string or null if invalid/empty
$katakana = $form->furigana->getKatakana();  // string|null

HiraganaInput

Automatically converts input to hiragana and validates that the result contains only hiragana characters.

use Coroq\Form\Form;
use Coroq\Form\Lang\Ja\FormItem\HiraganaInput;

class CommentForm extends Form {
    public readonly HiraganaInput $reading;

    public function __construct() {
        $this->reading = (new HiraganaInput())
            ->setLabel('よみがな')
            ->setMaxLength(100);
    }
}

$form = new CommentForm();

// Automatic conversion to hiragana
$form->reading->setValue('ヤマダタロウ');  // Katakana
echo $form->reading->getValue();  // "やまだたろう" (hiragana)

$form->reading->setValue('ﾔﾏﾀﾞﾀﾛｳ');     // Half-width
echo $form->reading->getValue();  // "やまだたろう" (hiragana)

// Long dash is accepted
$form->reading->setValue('こーひー');
$form->validate();  // true

Accepted Characters

• Hiragana: ぁ-ゔ
• Long dash: ー (less common in hiragana, but accepted)
• Combining marks: ゙゚ (for Unicode normalization)

Type-Safe Access

// Returns validated hiragana string or null if invalid/empty
$hiragana = $form->reading->getHiragana();  // string|null

Error Messages

BasicErrorMessages is a predefined set of Japanese error messages that can be used as-is or as a starting point for customization:

use Coroq\Form\ErrorMessageFormatter;
use Coroq\Form\Lang\Ja\BasicErrorMessages;

$formatter = new ErrorMessageFormatter();
$formatter->setMessages(BasicErrorMessages::get());

$form->validate();

if ($form->furigana->hasError()) {
    echo $formatter->format($form->furigana->getError());
    // "カタカナで入力してください"
}

Included Messages

// Japanese-specific errors
NotKatakanaError => "カタカナで入力してください"
NotHiraganaError => "ひらがなで入力してください"

// Common errors (from coroq/form)
EmptyError => "入力してください" or "選択してください"
InvalidError => "正しく入力してください"
InvalidEmailError => "正しいメールアドレスを入力してください"
InvalidUrlError => "正しい URL を入力してください"
TooLongError => "{length} 文字以内で入力してください"
TooShortError => "{length} 文字以上で入力してください"
TooSmallError => "{min} 以上の値を入力してください"
TooLargeError => "{max} 以下の値を入力してください"
NotIntegerError => "整数を入力してください"
// ... and more

Customizing Messages

use Coroq\Form\ErrorMessageFormatter;
use Coroq\Form\Lang\Ja\BasicErrorMessages;
use Coroq\Form\Lang\Ja\Error\NotKatakanaError;

$formatter = new ErrorMessageFormatter();

// Start with defaults
$messages = BasicErrorMessages::get();

// Override specific messages
$messages[NotKatakanaError::class] = "全角片仮名で入力してください";

$formatter->setMessages($messages);

Testing

composer test
composer coverage       # HTML coverage report → coverage/
composer coverage-text  # Text coverage report

License

MIT