Reemplazar sólo la primera ocurrencia en un texto por otro

Code Develium
Código PHP

PHP – String – Reemplazar primera ocurrencia

Función que reemplaza sólo la primera ocurrencia, empezando a buscar desde al izquierda, de un texto determinado por otro.

El reemplazo se realiza sin importar las mayúsculas y minúsculas. Si no existe la ocurrencia a buscar no se sustituye nada y devuelve el mismo rexto.

/**
 * Class HelperString
 */
abstract class HelperString
{
    /**
     * Reemplaza sólo la primera ocurrencia de un texto por otro.
     * Es insensible a mayúsculas y minúsculas pero no a los acentos.
     * Si no existe la ocurrencia, devuelve el mismo string
     *
     * @param string $txt
     * @param string $origen
     * @param string $destino
     *
     * @return string
     */

    public static function replaceFirst( $txt, $origen, $destino )
    {
        $origen = '/'.preg_quote( ''.$origen, '/' ).'/i';

        return ''.preg_replace( $origen, ''.$destino, ''.$txt, 1 );
    }

}

Ejemplos

$str = "123_123_123";
$ret = HelperString::replaceFirst($str, '1', "X");
echo $ret; // X23_123_123

$str = "abc defgh, abc defgh";
$ret = HelperString::replaceFirst($str, 'efg', "_");
echo $ret; // abc d_h, abc defgh

$str = "abc defgh abc defgHI";
$ret = HelperString::replaceFirst($str, 'eFg', "__X__");
echo $ret; // abc d__X__h abc defgHI

$str = "Función generación";
$ret = HelperString::replaceFirst($str, 'CIóN', "y");
echo $ret; // Funy generación

$str = "Función generación";
$ret = HelperString::replaceFirst($str, 'CIÓN', "y");
echo $ret; // Función generación