Page Contents

NumberHelper

class NumberHelper(View $view, array $settings = array())

Le helper Number contient des méthodes pratiques qui permettent l’affichage des nombres dans divers formats communs dans vos vues. Ces méthodes contiennent des moyens pour formater les devises, pourcentages, taille des données, le format des nombres avec précisions et aussi de vous donner davantage de souplesse en matière de formatage des nombres.

Modifié dans la version 2.1: NumberHelper a été remanié dans une classe CakeNumber pour permettre une utilisation plus facile a l’extérieur de la couche View. Dans une vue, ces méthodes sont accessibles via la classe NumberHelper et vous pouvez l’appeler comme vous pourriez appeler une méthode de helper normale: $this->Number->method($args);.

Toutes ces fonctions retournent le nombre formaté; Elles n’affichent pas automatiqement la sortie dans la vue.

NumberHelper::currency(float $number, string $currency = 'USD', array $options = array())
Paramètres:
  • $number (float) – La valeur à convertir.
  • $currency (string) – Le format de monnaie connu à utiliser.
  • $options (array) – Options, voir ci-dessous.

Cette méthode est utilisée pour afficher un nombre dans des formats de monnaie courante (EUR,GBP,USD). L’utilisation dans une vue ressemble à ceci:

// Appelé avec NumberHelper
echo $this->Number->currency($number, $currency);

// Appelé avec CakeNumber
App::uses('CakeNumber', 'Utility');
echo CakeNumber::currency($number, $currency);

Le premier paramètre $number, doit être un nombre à virgule qui représente le montant d’argent que vous désirez. Le second paramètre est utilisé pour choisir un schéma de formatage de monnaie courante:

$currency 1234.56, formaté par le type courant
EUR €1.234,56
GBP £1,234.56
USD $1,234.56

Le troisième paramètre est un tableau d’options pour définir la sortie. Les options suivantes sont disponibles:

Option Description
before Le symbole de la monnaie à placer avant les nombres ex: ‘$’
after Le symbole de la monnaie à placer après les nombres décimaux ex: ‘c’. Définit le booléen à false pour utiliser aucun symbole décimal ex: 0.35 => $0.35.
zero Le texte à utiliser pour des valeurs à zéro, peut être une chaîne de caractères ou un nombre. ex: 0, ‘Free!’
places Nombre de décimales à utiliser. ex: 2
thousands Séparateur des milliers ex: ‘,’
decimals Symbole de Séparateur des décimales. ex: ‘.’
negative Symbole pour les nombres négatifs. Si égal à ‘()’, le nombre sera entouré avec ( et )
escape La sortie doit-elle être échappée de htmlentity? Par défaut défini à true
wholeSymbol La chaîne de caractères à utiliser pour les tous nombres. ex: ‘ dollars’
wholePosition Soit ‘before’ soit ‘after’ pour placer le symbole entier
fractionSymbol Chaîne de caractères à utiliser pour les nombres en fraction. ex: ‘ cents’
fractionPosition Soit ‘before’ soit ‘after’ pour placer le symbole de fraction
fractionExponent Fraction exponent de cette monnaie spécifique. Par défaut à 2.

Si une valeur $currency non reconnue est fournie, elle est préfixée par un nombre formaté en USD. Par exemple:

// Appelé avec NumberHelper
echo $this->Number->currency('1234.56', 'FOO');

// Sortie
FOO 1,234.56

// Appelé avec CakeNumber
App::uses('CakeNumber', 'Utility');
echo CakeNumber::currency('1234.56', 'FOO');
NumberHelper::defaultCurrency(string $currency)
Paramètres:

Setter/getter pour la monnaie par défaut. Ceci retire la nécessité de toujours passer la monnaie à CakeNumber::currency() et change toutes les sorties de monnaie en définissant les autres par défaut.

Nouveau dans la version 2.3: Cette méthode a été ajoutée dans 2.3.

NumberHelper::addFormat(string $formatName, array $options)
Paramètres:
  • $formatName (string) – Le nom du format à utiliser dans le futur.
  • $options (array) –

    Le tableau d’options pour ce format. Utilise les mêmes clés $options comme CakeNumber::currency().

    • before Symbole de monnaie avant le nombre. False pour aucun.
    • after Symbole de monnaie après le nombre. False pour aucun.
    • zero Le texte à utiliser pour les valeurs à zéro, peut être une chaîne de caractères ou un nombre. ex: 0, ‘Free!’
    • places Nombre de décimal à utiliser. ex. 2.
    • thousands Séparateur des milliers. ex: ‘,’.
    • decimals Symbole de Séparateur des décimales. ex: ‘.’.
    • negative Symbole pour les nombres négatifs. Si égal à ‘()’, le nombre sera entouré avec ( et ).
    • escape La sortie doit-elle être échappée de htmlentity? Par défaut à true.
    • wholeSymbol Chaîne de caractères à utiliser pour tous les nombres. ex: ‘ dollars’.
    • wholePosition Soit ‘before’ soit ‘after’ pour placer le symbole complet.
    • fractionSymbol Chaîne de caractères à utiliser pour les nombres à fraction. ex: ‘ cents’.
    • fractionPosition Soit ‘before’ soit ‘after’ pour placer le symbole de fraction.

Ajoute le format de monnaie au helper Number. Facilite la réutilisation des formats de monnaie.

// appelé par NumberHelper
$this->Number->addFormat('BRL', array('before' => 'R$', 'thousands' => '.', 'decimals' => ','));

// appelé par CakeNumber
App::uses('CakeNumber', 'Utility');
CakeNumber::addFormat('BRL', array('before' => 'R$', 'thousands' => '.', 'decimals' => ','));

Vous pouvez maintenant utiliser BRL de manière courte quand vous formatez les montants de monnaie:

// appelé par NumberHelper
echo $this->Number->currency($value, 'BRL');

// appelé par CakeNumber
App::uses('CakeNumber', 'Utility');
echo CakeNumber::currency($value, 'BRL');

Les formats ajoutés sont fusionnés avec les formats par défaut suivants:

array(
    'wholeSymbol'      => '',
    'wholePosition'    => 'before',
    'fractionSymbol'   => false,
    'fractionPosition' => 'after',
    'zero'             => 0,
    'places'           => 2,
    'thousands'        => ',',
    'decimals'         => '.',
    'negative'         => '()',
    'escape'           => true,
    'fractionExponent' => 2
)
NumberHelper::precision(mixed $number, int $precision = 3)
Paramètres:
  • $number (float) – La valeur à convertir
  • $precision (integer) – Le nombre de décimal à afficher

Cette méthode affiche un nombre avec le montant de précision spécifié (place de la décimal). Elle arrondira afin de maintenir le niveau de précision défini.

// appelé avec NumberHelper
echo $this->Number->precision(456.91873645, 2 );

// Sortie
456.92

// appelé avec CakeNumber
App::uses('CakeNumber', 'Utility');
echo CakeNumber::precision(456.91873645, 2 );
NumberHelper::toPercentage(mixed $number, int $precision = 2, array $options = array())
Paramètres:
  • $number (float) – La valeur à convertir.
  • $precision (integer) – Le nombre de décimal à afficher.
  • $options (array) – Options, voir ci-dessous.
Option Description
multiply Booléen pour indiquer si la valeur doit être multipliée par 100. Utile pour les pourcentages avec décimal.

Comme precision(), cette méthode formate un nombre selon la précision fournie (où les nombres sont arrondis pour parvenir à ce degré de précision). Cette méthode exprime aussi le nombre en tant que pourcentage et préfixe la sortie avec un signe de pourcent.

// appelé avec NumberHelper. Sortie: 45.69%
echo $this->Number->toPercentage(45.691873645);

// appelé avec CakeNumber. Sortie: 45.69%
App::uses('CakeNumber', 'Utility');
echo CakeNumber::toPercentage(45.691873645);

// Appelé avec multiply. Sortie: 45.69%
echo CakeNumber::toPercentage(0.45691, 2, array(
    'multiply' => true
));

Nouveau dans la version 2.4: L’argument $options avec l’option multiply a été ajouté.

NumberHelper::fromReadableSize(string $size, $default)
Paramètres:
  • $size (string) – La valeur formatée lisible par un humain.

Cette méthode enlève le format d’un nombre à partir d’une taille de byte lisible par un humain en un nombre entier de bytes.

Nouveau dans la version 2.3: Cette méthode a été ajoutée dans 2.3

NumberHelper::toReadableSize(string $dataSize)
Paramètres:
  • $data_size (string) – Le nombre de bytes pour le rendre lisible.

Cette méthode formate les tailles de données dans des formes lisibles pour l’homme. Elle fournit une manière raccourcie de convertir les en KB, MB, GB, et TB. La taille est affichée avec un niveau de précision à deux chiffres, selon la taille de données fournie (ex: les tailles supérieurs sont exprimées dans des termes plus larges):

// appelé avec NumberHelper
echo $this->Number->toReadableSize(0); // 0 Bytes
echo $this->Number->toReadableSize(1024); // 1 KB
echo $this->Number->toReadableSize(1321205.76); // 1.26 MB
echo $this->Number->toReadableSize(5368709120); // 5.00 GB

// appelé avec CakeNumber
App::uses('CakeNumber', 'Utility');
echo CakeNumber::toReadableSize(0); // 0 Bytes
echo CakeNumber::toReadableSize(1024); // 1 KB
echo CakeNumber::toReadableSize(1321205.76); // 1.26 MB
echo CakeNumber::toReadableSize(5368709120); // 5.00 GB
NumberHelper::format(mixed $number, mixed $options=false)

Cette méthode vous donne beaucoup plus de contrôle sur le formatage des nombres pour l’utilisation dans vos vues (et est utilisée en tant que méthode principale par la plupart des autres méthodes de NumberHelper). L’utilisation de cette méthode pourrait ressembler à cela:

// appelé avec NumberHelper
$this->Number->format($number, $options);

// appelé avec CakeNumber
CakeNumber::format($number, $options);

Le paramètre $number est le nombre que vous souhaitez formater pour la sortie. Avec aucun $options fourni, le nombre 1236.334 sortirait comme ceci : 1,236. Notez que la précision par défaut est d’aucun chiffre après la virgule.

Le paramètre $options est là où réside la réelle magie de cette méthode.

  • Si vous passez un entier alors celui-ci devient le montant de précision pour la fonction.
  • Si vous passez un tableau associatif, vous pouvez utiliser les clés suivantes:
    • places (integer): le montant de précision désiré.
    • before (string): à mettre avant le nombre à sortir.
    • escape (boolean): si vous voulez la valeur avant d’être échappée.
    • decimals (string): utilisé pour délimiter les places des décimales dans le nombre.
    • thousands (string): utilisé pour marquer les milliers, millions, …

Exemple:

// appelé avec NumberHelper
echo $this->Number->format('123456.7890', array(
    'places' => 2,
    'before' => '¥ ',
    'escape' => false,
    'decimals' => '.',
    'thousands' => ','
));
// sortie '¥ 123,456.79'

// appelé avec CakeNumber
App::uses('CakeNumber', 'Utility');
echo CakeNumber::format('123456.7890', array(
    'places' => 2,
    'before' => '¥ ',
    'escape' => false,
    'decimals' => '.',
    'thousands' => ','
));
// sortie '¥ 123,456.79'
NumberHelper::formatDelta(mixed $number, mixed $options=array())

Cette méthode affiche les différences en valeur comme un nombre signé:

// appelé avec NumberHelper
$this->Number->formatDelta($number, $options);

// appelé avec CakeNumber
CakeNumber::formatDelta($number, $options);

Le paramètre $number est le nombre que vous planifiez sur le formatage de sortie. Avec aucun $options fourni, le nombre 1236.334 sortirait 1,236. Notez que la valeur de précision par défaut est aucune décimale.

Le paramètre $options prend les mêmes clés que CakeNumber::format() lui-même:

  • places (integer): le montant de precision souhaité.
  • before (string): à mettre avant le nombre sorti.
  • after (string): à mettre après le nombre sorti.
  • decimals (string): utilisé pour délimiter les places de la décimal dans un nombre.
  • thousands (string): utilisé pour marquer les places des centaines, millions, …

Exemple:

// appelé avec NumberHelper
echo $this->Number->formatDelta('123456.7890', array(
    'places' => 2,
    'decimals' => '.',
    'thousands' => ','
));
// sortie '+123,456.79'

// appelé avec CakeNumber
App::uses('CakeNumber', 'Utility');
echo CakeNumber::formatDelta('123456.7890', array(
    'places' => 2,
    'decimals' => '.',
    'thousands' => ','
));
// sortie '+123,456.79'

Nouveau dans la version 2.3: Cette méthode a été ajoutée dans 2.3.

Avertissement

Depuis 2.4 les symboles sont maintenant en UTF-8. Merci de regarder le guide de migration pour plus de détails si vous lancez une application non-UTF-8.