Shows how to define a custom format tag for a caclulated field in Participants Database

pdb-custom-format-tag.php

<?php

/**
 * Plugin Name: PDB Custom Format Tag
 * Description: shows how to add a custom formatting tag for use in a Participants Database calculated field
 * Version: 1.0
 * Tutorial: https://xnau.com/using-custom-format-tags-for-calculation-fields/
 * 
 * this requires Participants Database version 2.4.8 or later!
 */

class PDb_custom_format_tag
{
  /**
   * sets up the filters
   */
  public function __construct()
  {
    /*
     * this is the name of the tag 
     * to use this in the calculated field, the tag will be: [?years_or_months]
     */
    $tag = 'years_or_months';
    
    // this sets up the function to be called to fill in the value for the tag
    add_filter( 'pdb-calc_field_format_tag_' . $tag, array( $this, 'custom_tag_value' ), 10, 2 );
      
    // use this if the tag is for display purposes only
    add_filter( 'pdb-display_only_format_tag_' . $tag, function(){ return true; } );
  }
  
  /**
   * provides the years_or_months tag value
   * 
   * @param string $value the raw result of the calculation (the person's age as the number of seconds old they are)
   * @param \PDb_Field_Item $field the current field
   * @return string
   */
  public function custom_tag_value( $value, $field )
  {
    $years = $value / YEAR_IN_SECONDS;
    $whole_years = $this->truncate_number( $years );
    $months = $this->truncate_number( $value / MONTH_IN_SECONDS ) - ($whole_years * 12);
    
    /*
     * this is set up to show the age as months if less than 1 year, shows months 
     * and years if between 1 and 3 years and the number of whole years if the 
     * age is 3 or over.
     */
    switch(true)
    {
      case $years < 1:
        
        $age = $months . ( $months > 1 ? ' months' : ' month' );
        break;
      
      case $years < 3:
        
        $age = $whole_years . ( $whole_years > 1 ? ' years' : ' year' );
        
        if ( $months > 0 )
        {
          $age .=  ', ' . $months . ( $months > 1 ? ' months' : ' month' );
        }
        break;
      
      case $years >= 3:
        
        $age = $whole_years . ' years';
    }
    
    return $age;
  }

  /**
   * truncates the fractional part of a float without rounding
   * 
   * @param float $number
   * @return int
   */
  private function truncate_number( $number )
  {
    // if there's no decimal just return the value
    if ( strpos( $number, '.' ) === false ) {
      return $number;
    }

    // split the number into the integer and fractional parts
    list( $int, $frac ) = explode( '.', $number );

    // return the integer portion
    return (int) $int;
  }
}

new PDb_custom_format_tag();

To use this code, install this script as a plugin. The meat of this is all in the PDb_custom_format_tag::custom_tag_value() method, to make your own tag, you'll need to:

1. Set the name of your tag (line 22)
2. Change the custom_tag_value method to return the desired formatting of the incoming value
3. once the plugin is installed and activated, use the tag in the field's calculation template
4. once the field is saved, all records will be updated with the new tag value

Format tags can take one of two forms: they eithr set the value to be saved, or they are for display purposes only. This example is for display purposes only, it does not affect the value that is saved.