      1: <?php
      2: /**
      3:  * DataTables PHP libraries.
      4:  *
      5:  * PHP libraries for DataTables and DataTables Editor, utilising PHP 5.3+.
      6:  *
      7:  *  @author    SpryMedia
      8:  *  @copyright 2012 SpryMedia ( http://sprymedia.co.uk )
      9:  *  @license   http://editor.datatables.net/license DataTables Editor
     10:  *  @link      http://editor.datatables.net
     11:  */
     12:
     13: namespace DataTables\Editor;
     14: if (!defined('DATATABLES')) exit();
     15:
     16:
     17: /**
     18:  * Formatter methods for the DataTables Editor
     19:  *
     20:  * All methods in this class are static with common inputs and returns.
     21:  */
     22: class Format {
     23:     /** Date format: 2012-03-09. jQuery UI equivalent format: yy-mm-dd */
     24:     const DATE_ISO_8601 = "Y-m-d";
     25:
     26:     /** Date format: Fri, 9 Mar 12. jQuery UI equivalent format: D, d M y */
     27:     const DATE_ISO_822 = "D, j M y";
     28:
     29:     /** Date format: Friday, 09-Mar-12.  jQuery UI equivalent format: DD, dd-M-y */
     30:     const DATE_ISO_850 = "l, d-M-y";
     31:
     32:     /** Date format: Fri, 9 Mar 12. jQuery UI equivalent format: D, d M y */
     33:     const DATE_ISO_1036 = "D, j M y";
     34:
     35:     /** Date format: Fri, 9 Mar 2012. jQuery UI equivalent format: D, d M yy */
     36:     const DATE_ISO_1123 = "D, j M Y";
     37:
     38:     /** Date format: Fri, 9 Mar 2012. jQuery UI equivalent format: D, d M yy */
     39:     const DATE_ISO_2822 = "D, j M Y";
     40:
     41:     /** Date format: March-. jQuery UI equivalent format: D, d M yy */
     42:     const DATE_USA = "m-d-Y";
     43:
     44:     /** Date format: 1331251200. jQuery UI equivalent format: @ */
     45:     const DATE_TIMESTAMP = "U";
     46:
     47:     /** Date format: 1331251200. jQuery UI equivalent format: @ */
     48:     const DATE_EPOCH = "U";
     49:
     50:
     51:     /**
     52:      * Convert from SQL date / date time format to a format given by the options
     53:      * parameter.
     54:      *
     55:      * Typical use of this method is to use it with the
     56:      * {@link Field::getFormatter} and {@link Field::setFormatter} methods of
     57:      * {@link Field} where the parameters required for this method will be
     58:      * automatically satisfied.
     59:      *   @param string $val Value to convert from MySQL date format
     60:      *   @param string[] $data Data for the whole row / submitted data
     61:      *   @param string $opts Format to convert to using PHP date() options.
     62:      *   @return string Formatted date or empty string on error.
     63:      */
     64:     public static function dateSqlToFormat( $format ) {
     65:         return function ( $val, $data ) use ( $format ) {
     66:             $date = new \DateTime( $val );
     67:
     68:             // Allow empty strings or invalid dates
     69:             if ( $val && $date ) {
     70:                 return date_format( $date, $format );
     71:             }
     72:             return null;
     73:         };
     74:     }
     75:
     76:
     77:     /**
     78:      * Convert from a format given by the options parameter to a format that
     79:      * SQL servers will recognise as a date.
     80:      *
     81:      * Typical use of this method is to use it with the
     82:      * {@link Field::getFormatter} and {@link Field::setFormatter} methods of
     83:      * {@link Field} where the parameters required for this method will be
     84:      * automatically satisfied.
     85:      *   @param string $val Value to convert to SQL date format
     86:      *   @param string[] $data Data for the whole row / submitted data
     87:      *   @param string $opts Format to convert from using PHP date() options.
     88:      *   @return string Formatted date or null on error.
     89:      */
     90:     public static function dateFormatToSql( $format ) {
     91:         return function ( $val, $data ) use ( $format ) {
     92:             // Note that this assumes the date is in the correct format (should be
     93:             // checked by validation before being used here!)
     94:             if ( substr($format, 0, 1) !== '!' ) {
     95:                 $format = '!'.$format;
     96:             }
     97:             $date = date_create_from_format($format, $val);
     98:
     99:             // Invalid dates or empty string are replaced with null. Use the
    100:             // validation to ensure the date given is valid if you don't want this!
    101:             if ( $val && $date ) {
    102:                 return date_format( $date, 'Y-m-d' );
    103:             }
    104:             return null;
    105:         };
    106:     }
    107:
    108:
    109:     /**
    110:      * Convert from one date time format to another
    111:      *
    112:      * Typical use of this method is to use it with the
    113:      * {@link Field::getFormatter} and {@link Field::setFormatter} methods of
    114:      * {@link Field} where the parameters required for this method will be
    115:      * automatically satisfied.
    116:      *   @param string $val Value to convert
    117:      *   @param string[] $data Data for the whole row / submitted data
    118:      *   @param string $opts Array with `from` and `to` properties which are the
    119:      *     formats to convert from and to
    120:      *   @return string Formatted date or null on error.
    121:      */
    122:     public static function datetime( $from, $to ) {
    123:         return function ( $val, $data ) use ( $from, $to ) {
    124:             if ( substr($from, 0, 1) !== '!' ) {
    125:                 $from = '!'.$from;
    126:             }
    127:             $date = date_create_from_format( $from, $val );
    128:
    129:             // Allow empty strings or invalid dates
    130:             if ( $date ) {
    131:                 return date_format( $date, $to );
    132:             }
    133:
    134:             return null;
    135:         };
    136:     }
    137:
    138:
    139:     /**
    140:      * Convert a string of values into an array for use with checkboxes.
    141:      *   @param string $val Value to convert to from a string to an array
    142:      *   @param string[] $data Data for the whole row / submitted data
    143:      *   @param string $opts Field delimiter
    144:      *   @return string Formatted value or null on error.
    145:      */
    146:     public static function explode( $char='|' ) {
    147:         return function ( $val, $data ) use ( $char ) {
    148:             return explode($char, $val);
    149:         };
    150:     }
    151:
    152:
    153:     /**
    154:      * Convert an array of values from a checkbox into a string which can be
    155:      * used to store in a text field in a database.
    156:      *   @param string $val Value to convert to from an array to a string
    157:      *   @param string[] $data Data for the whole row / submitted data
    158:      *   @param string $opts Field delimiter
    159:      *   @return string Formatted value or null on error.
    160:      */
    161:     public static function implode( $char='|' ) {
    162:         return function ( $val, $data ) use ( $char ) {
    163:             return implode($char, $val);
    164:         };
    165:     }
    166:
    167:
    168:     /**
    169:      * Convert an empty string to `null`. Null values are very useful in
    170:      * databases, but HTTP variables have no way of representing `null` as a
    171:      * value, often leading to an empty string and null overlapping. This method
    172:      * will check the value to operate on and return null if it is empty.
    173:      *   @param string $val Value to convert to from a string to an array
    174:      *   @param string[] $data Data for the whole row / submitted data
    175:      *   @param string $opts Field delimiter
    176:      *   @return string Formatted value or null on error.
    177:      */
    178:     public static function nullEmpty () {
    179:         // Legacy function - use `ifEmpty` now
    180:         return self::ifEmpty( null );
    181:     }
    182:
    183:
    184:     /**
    185:      * Formatter that can be used to specify what value should be used if an
    186:      * empty value is submitted by the client-side (e.g. null, 0, 'Not set',
    187:      * etc)
    188:      *   @param string $val Value to convert to from a string to an array
    189:      *   @param string[] $data Data for the whole row / submitted data
    190:      *   @param string $opts Empty value
    191:      *   @return string Formatted value or null on error.
    192:      */
    193:     public static function ifEmpty ( $ret ) {
    194:         return function ( $val, $data ) use ( $ret ) {
    195:             return $val === '' ?
    196:                 $ret :
    197:                 $val;
    198:         };
    199:     }
    200:
    201:
    202:     /**
    203:      * Convert a number from using any character other than a period (dot) to
    204:      * one which does use a period. This is useful for allowing numeric user
    205:      * input in regions where a comma is used as the decimal character. Use with
    206:      * a set formatter.
    207:      *   @param string $val Value to convert to from a string to an array
    208:      *   @param string[] $data Data for the whole row / submitted data
    209:      *   @param string $opts Decimal place character (default ',')
    210:      *   @return string Formatted value or null on error.
    211:      */
    212:     public static function fromDecimalChar ( $char=',' ) {
    213:         return function ( $val, $data ) use ( $char ) {
    214:             return str_replace( $char, '.', $val );
    215:         };
    216:     }
    217:
    218:
    219:     /**
    220:      * Convert a number with a period (dot) as the decimal character to use
    221:      * a different character (typically a comma). Use with a get formatter.
    222:      *   @param string $val Value to convert to from a string to an array
    223:      *   @param string[] $data Data for the whole row / submitted data
    224:      *   @param string $opts Decimal place character (default ',')
    225:      *   @return string Formatted value or null on error.
    226:      */
    227:     public static function toDecimalChar ( $char=',' ) {
    228:         return function ( $val, $data ) use ( $char ) {
    229:             return str_replace( '.', $char, $val );
    230:         };
    231:     }
    232:
    233:
    234:
    235:     /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    236:      * Internal functions
    237:      * These legacy methods are for backwards compatibility with the old way of
    238:      * using the formatter methods. They basically do argument swapping.
    239:      */
    240:
    241:     /**
    242:      * @internal
    243:      */
    244:     public static function date_sql_to_format ( $opts ) {
    245:         return self::dateSqlToFormat( $opts );
    246:     }
    247:
    248:     /**
    249:      * @internal
    250:      */
    251:     public static function date_sql_to_formatLegacy ( $opts ) {
    252:         return self::dateSqlToFormat( $opts );
    253:     }
    254:
    255:     /**
    256:      * @internal
    257:      */
    258:     public static function date_format_to_sql ( $opts ) {
    259:         return self::dateFormatToSql( $opts );
    260:     }
    261:
    262:     /**
    263:      * @internal
    264:      */
    265:     public static function date_format_to_sqlLegacy ( $opts ) {
    266:         return self::dateFormatToSql( $opts );
    267:     }
    268:
    269:     /**
    270:      * @internal
    271:      */
    272:     public static function datetimeLegacy ( $opts ) {
    273:         return self::datetime( $opts['from'], $opts['to'] );
    274:     }
    275:
    276:     /**
    277:      * @internal
    278:      */
    279:     public static function explodeLegacy ( $opts ) {
    280:         if ( $opts === null ) {
    281:             $opts = '|';
    282:         }
    283:         return self::explode( $opts );
    284:     }
    285:
    286:     /**
    287:      * @internal
    288:      */
    289:     public static function implodeLegacy ( $opts ) {
    290:         if ( $opts === null ) {
    291:             $opts = '|';
    292:         }
    293:         return self::implode( $opts );
    294:     }
    295:
    296:     /**
    297:      * @internal
    298:      */
    299:     public static function nullEmptyLegacy ( $opts ) {
    300:         return self::nullEmpty( null );
    301:     }
    302:
    303:     /**
    304:      * @internal
    305:      */
    306:     public static function ifEmptyLegacy ( $opts ) {
    307:         return self::ifEmpty( $opts );
    308:     }
    309:
    310:     /**
    311:      * @internal
    312:      */
    313:     public static function fromDecimalCharLegacy ( $opts ) {
    314:         if ( $opts === null ) {
    315:             $opts = ',';
    316:         }
    317:         return self::fromDecimalChar( $opts );
    318:     }
    319:
    320:     /**
    321:      * @internal
    322:      */
    323:     public static function toDecimalCharLegacy ( $opts ) {
    324:         if ( $opts === null ) {
    325:             $opts = ',';
    326:         }
    327:         return self::toDecimalChar( $opts );
    328:     }
    329: }
    330:
    331: