CodeIgniterのset_value()とは何か？

CodeIgniterにはset_value()というヘルパー関数があるのですが、仕様や意図が少しわかりづらいので、調査して整理しておきます。

このヘルパーの意味

3.2.0-devのユーザガイドでは、以下のように説明されています。

入力フォームやテキストエリアの値を設定します。関数の第1引数でフィールド名を指定します。第2引数（オプション）では、フォームの初期値を指定できます。
http://codeigniter.jp/user_guide/3/helpers/form_helper.html#set_value

また、Noteとして、以下の記述があります。

フォームバリデーション (検証) をロードしこのヘルパーで使われているフィールド名の検証ルールを設定している場合、フォームバリデーション (検証) 自身の set_value() メソッドの呼び出しを行います。それ以外の場合、この関数はフィールドの値を設定するために $_POST を参照します。

念のため、3.1.0の本家のユーザガイド http://www.codeigniter.com/userguide3/helpers/form_helper.html#set_value も見ておきましょう。

Permits you to set the value of an input form or textarea. You must supply the field name via the first parameter of the function. The second (optional) parameter allows you to set a default value for the form.

Noteも。

If you’ve loaded the Form Validation Library and have set a validation rule for the field name in use with this helper, then it will forward the call to the Form Validation Library‘s own set_value() method. Otherwise, this function looks in $_POST for the field value.

同じですね。

つまり、このヘルパーはFormからの入力値を返すもので、Form_validationクラスと関連するが、必ずしもForm_validationと一緒に使う必要があるわけではないということになります。ちょっとわかりにくいですね。

実装

具体的な実装を確認しておきましょう。

CodeIgniter 3.1.0

    function set_value($field, $default = '', $html_escape = TRUE)
    {
        $CI =& get_instance();

        $value = (isset($CI->form_validation) && is_object($CI->form_validation) && $CI->form_validation->has_rule($field))
            ? $CI->form_validation->set_value($field, $default)
            : $CI->input->post($field, FALSE);

        isset($value) OR $value = $default;
        return ($html_escape) ? html_escape($value) : $value;
    }

現在の実装は、Form_validationがロードされており、指定フィールドに対する検証ルールがあれば、Form_validation::set_value()メソッドの返り値を、そうでなければPOSTパラメータから値を取得し、最後にHTMLエスケープして（デフォルトの場合）います。

つまり、Form_validationクラスを使わなくても、このヘルパー関数はPOSTパラメータの値をエスケープして返します。

はい、ユーザガイドに書いてある通りですね。

ただし、Form_validationクラスがロードされ、検証ルールが定義されている場合は、Form_validation::run()メソッドを実行しないとset_value()は入力値を返しません。

なぜなら、Form_validation::set_value()メソッドは以下のようになっているからです。Form_validation::run()メソッドを実行しないと$this->_field_data[$field]['postdata'])の値がセットされないからです。

    public function set_value($field = '', $default = '')
    {
        if ( ! isset($this->_field_data[$field], $this->_field_data[$field]['postdata']))
        {
            return $default;
        }

        // If the data is an array output them one at a time.
        //  E.g: form_input('name[]', set_value('name[]');
        if (is_array($this->_field_data[$field]['postdata']))
        {
            return array_shift($this->_field_data[$field]['postdata']);
        }

        return $this->_field_data[$field]['postdata'];
    }

CodeIgniter 2.2.6

過去のバージョンでの実装も見ておきましょう。

    function set_value($field = '', $default = '')
    {
        if (FALSE === ($OBJ =& _get_validation_object()))
        {
            if ( ! isset($_POST[$field]))
            {
                return $default;
            }

            return form_prep($_POST[$field], $field);
        }

        return form_prep($OBJ->set_value($field, $default), $field);
    }

やっていることはほぼ同じです。

CodeIgniter 1.7.3

    function set_value($field = '', $default = '')
    {
        if (FALSE === ($OBJ =& _get_validation_object()))
        {
            if ( ! isset($_POST[$field]))
            {
                return $default;
            }

            return form_prep($_POST[$field], $field);
        }

        return form_prep($OBJ->set_value($field, $default), $field);
    }

2.2と同じです。

CodeIgniter 1.6.1

なし。

いつ追加されたのか？

では、この関数はいつ追加されたのでしょうか？

27 Aug 2008に追加されています。https://github.com/bcit-ci/CodeIgniter/commit/43e0fbb650d05466cd2568b8a2cc1c38849a6b52#diff-1c29a972aad2e090993d30d846a74282R592 より。

+   function set_value($field = '', $default = '')
+   {
+       if (FALSE === ($OBJ =& _get_validation_object()))
+       {
+           if ( ! isset($_POST[$field]))
+           {
+               return $default;
+           }
+           
+           return $_POST[$field];
+       }
+       
+       return $OBJ->set_value($field, $default);
+   }

当初はHTMLエスケープしていませんでしたが、その後、エスケープ処理が追加されたようです。