PHP Functions: Parameters and Return Values

Duration: 45 minutes

Module 2: Functions in PHP

Learning Objectives

Create and use PHP functions
Understand function parameters and returns
Master variable scope in functions
Build reusable code components

Making Functions Dynamic and Useful

Welcome back to our exploration of PHP functions! In our previous lecture, we learned how to declare and call functions. Now, we'll make our functions truly powerful by understanding parameters and return values.

Think of functions as specialized machines in a factory. In our last lecture, we built simple machines that always do the same thing. Today, we're upgrading these machines to accept different materials (parameters) and produce customized products (return values).

Key Concepts

Parameters: Values passed to a function to customize its behavior
Return Values: Data that a function sends back after completing its task

Function Parameters and Return Values: A Visual Model

Diagram

Imagine a coffee machine. You input coffee beans, water, and settings (parameters), and it outputs a cup of coffee (return value). The quality and type of coffee you get depends on what you put in and how the machine is programmed.

Function Parameters in PHP

Parameters allow our functions to work with different values each time they're called, making them flexible and reusable.

Basic Parameter Syntax

function functionName($parameter1, $parameter2) {
    // Code that uses $parameter1 and $parameter2
}

Simple Parameter Example

function greetUser($username) {
    echo "Hello, $username! Welcome to our WordPress site.";
}

// Calling the function with different parameters
greetUser("Sarah");    // Output: Hello, Sarah! Welcome to our WordPress site.
greetUser("Michael");  // Output: Hello, Michael! Welcome to our WordPress site.
greetUser("Developer"); // Output: Hello, Developer! Welcome to our WordPress site.

Unlike our previous function that always output the same greeting, this function customizes the greeting based on the parameter we provide.

Multiple Parameters Example

function calculateRectangleArea($length, $width) {
    $area = $length * $width;
    echo "A rectangle with length $length and width $width has an area of $area.";
}

calculateRectangleArea(5, 3);  // Output: A rectangle with length 5 and width 3 has an area of 15.
calculateRectangleArea(10, 7); // Output: A rectangle with length 10 and width 7 has an area of 70.

Parameter Order Matters!

function showUserRole($username, $role) {
    echo "$username has the role of $role.";
}

// The order of arguments must match the order of parameters
showUserRole("John", "Editor");    // Output: John has the role of Editor.
showUserRole("Editor", "John");    // Output: Editor has the role of John. (Incorrect!)

Working with Different Parameter Types

PHP is a loosely typed language, which means our functions can accept various data types as parameters. Let's explore how to work with different types.

Working with Different Parameter Types

// String parameter
function displayTitle($title) {
    echo "<h1>$title</h1>";
}
displayTitle("Welcome to My WordPress Site");

// Numeric parameter
function calculateTax($price, $taxRate) {
    $taxAmount = $price * ($taxRate / 100);
    echo "Tax amount: $" . number_format($taxAmount, 2);
}
calculateTax(49.99, 8.25);

// Boolean parameter
function showAdminContent($isAdmin) {
    if ($isAdmin) {
        echo "Welcome, Administrator! Here's your dashboard.";
    } else {
        echo "You don't have permission to view this content.";
    }
}
showAdminContent(true);

// Array parameter
function listCategories($categories) {
    echo "<ul>";
    foreach ($categories as $category) {
        echo "<li>$category</li>";
    }
    echo "</ul>";
}
listCategories(["WordPress", "PHP", "Development", "Plugins"]);

Type Declarations (Type Hinting)

While PHP is loosely typed, modern PHP (7.0+) allows you to specify what type of data a function should accept. This helps catch errors early and makes your code more robust.

Basic Type Declaration Syntax

function functionName(type $parameter) {
    // Code that uses $parameter
}

Type Declaration Examples

// String type declaration
function displayHeading(string $text) {
    echo "<h2>$text</h2>";
}

// Integer type declaration
function setPageLimit(int $limit) {
    echo "Displaying $limit posts per page.";
}

// Array type declaration
function processUserData(array $userData) {
    foreach ($userData as $key => $value) {
        echo "$key: $value<br>";
    }
}

// Mixed types example (PHP 8.0+)
function displayValue(mixed $value) {
    echo "The value is: $value";
}

If you try to pass a value of the wrong type, PHP will throw a TypeError exception:

function countCharacters(string $text) {
    return strlen($text);
}

// This will work
echo countCharacters("Hello WordPress");  // Output: 15

// This will cause an error
echo countCharacters(12345);  // TypeError: countCharacters(): Argument #1 ($text) must be of type string, int given

WordPress Compatibility Note

If you're developing for WordPress, be mindful that some environments might still run older PHP versions. Check the minimum requirements of your target WordPress environment before using newer PHP features like type declarations.

Function Return Values

So far, our functions have been performing actions (like displaying text) but not giving anything back. Return values allow functions to compute a result and send it back to where the function was called.

Basic Return Value Syntax

function functionName($parameter) {
    // Process the parameter
    $result = // some calculation or operation
    return $result;
}

Diagram

Simple Return Value Example

function addNumbers($a, $b) {
    $sum = $a + $b;
    return $sum;
}

// Storing the return value in a variable
$total = addNumbers(5, 7);
echo "The total is: $total";  // Output: The total is: 12

// Using the return value directly
echo "5 + 10 = " . addNumbers(5, 10);  // Output: 5 + 10 = 15

The key difference between this function and our earlier examples is that this function doesn't display anything itself. Instead, it computes a value and returns it, which gives us more flexibility in how we use the result.

Return Type Declarations

Just like with parameters, PHP 7.0+ allows you to specify the type of value a function will return. This helps ensure your function produces data of the expected type.

Return Type Declaration Syntax

function functionName($parameter): returnType {
    // Function code
    return $returnValue;
}

Return Type Examples

// String return type
function getUserName($userId): string {
    // Fetch user from database (simplified)
    $users = [
        1 => "JohnDoe",
        2 => "JaneSmith"
    ];
    
    return $users[$userId] ?? "Unknown User";
}

// Integer return type
function calculatePostCount(): int {
    // Count posts (simplified)
    return 42;
}

// Array return type
function getRecentPosts($count): array {
    // Fetch posts (simplified)
    return [
        "Introduction to WordPress",
        "Building Custom Themes",
        "PHP for Beginners"
    ];
}

// Bool return type
function userHasPermission($userId, $action): bool {
    // Check permissions (simplified)
    return ($userId === 1 && $action === "edit");
}

Return Type Enforcement

PHP will check the type of the returned value against the declared return type. If there's a mismatch, a TypeError will be thrown.

Real-World WordPress Examples

Let's explore how parameters and return values are used in WordPress development.

Custom Shortcode with Parameters

function customButton($atts) {
    // Define default parameter values
    $attributes = shortcode_atts(array(
        'text' => 'Click Me',
        'url' => '#',
        'color' => 'blue',
        'size' => 'medium'
    ), $atts);
    
    // Generate button HTML
    $buttonHtml = '<a href="' . esc_url($attributes['url']) . '" ';
    $buttonHtml .= 'class="custom-button ' . esc-attr($attributes['color']) . ' ' . esc_attr($attributes['size']) . '">';
    $buttonHtml .= esc_html($attributes['text']);
    $buttonHtml .= '</a>';
    
    // Return the generated HTML
    return $buttonHtml;
}
add_shortcode('custom_button', 'customButton');

// Usage in WordPress content:
// [custom_button text="Learn More" url="https://example.com" color="green" size="large"]

WordPress Template Function

/**
 * Retrieves formatted post excerpt
 *
 * @param int $post_id Post ID (optional)
 * @param int $length Maximum excerpt length in words
 * @param string $more Text to append if excerpt is trimmed
 * @return string Formatted excerpt
 */
function get_custom_excerpt($post_id = null, $length = 55, $more = '...'): string {
    // Get post by ID or use current post
    if ($post_id) {
        $post = get_post($post_id);
    } else {
        $post = get_post();
    }
    
    // If no post found, return empty string
    if (!$post) {
        return '';
    }
    
    // Get the excerpt
    $excerpt = $post->post_excerpt;
    
    // If no manual excerpt exists, generate one from content
    if (empty($excerpt)) {
        $excerpt = $post->post_content;
        $excerpt = strip_shortcodes($excerpt);
        $excerpt = wp_strip_all_tags($excerpt);
    }
    
    // Trim to desired length
    $words = explode(' ', $excerpt, $length + 1);
    if (count($words) > $length) {
        array_pop($words);
        $excerpt = implode(' ', $words) . $more;
    }
    
    return $excerpt;
}

// Example usage in a template file
echo '<p class="entry-excerpt">' . get_custom_excerpt(null, 30, ' [Read More...]') . '</p>';

Advanced Parameter Techniques

Named Arguments (PHP 8.0+)

PHP 8.0 introduced named arguments, which allow you to specify which parameter each value corresponds to, making your function calls more readable and allowing you to skip optional parameters.

function formatUserProfile($name, $role = 'Subscriber', $joinDate = null, $bio = '') {
    $output = "<div class='user-profile'>";
    $output .= "<h3>$name</h3>";
    $output .= "<p>Role: $role</p>";
    
    if ($joinDate) {
        $output .= "<p>Member since: $joinDate</p>";
    }
    
    if ($bio) {
        $output .= "<p>$bio</p>";
    }
    
    $output .= "</div>";
    return $output;
}

// Using positional arguments
echo formatUserProfile('John Doe', 'Editor', '2025-01-15', 'WordPress enthusiast and developer.');

// Using named arguments (PHP 8.0+)
echo formatUserProfile(
    name: 'Jane Smith',
    bio: 'PHP developer specializing in WordPress.',
    role: 'Administrator'
    // joinDate is skipped
);

Nullable Types (PHP 7.1+)

You can declare a parameter or return type as nullable by prefixing it with a question mark, allowing the value to be of the specified type or null.

function getUserAvatar(?int $userId): ?string {
    if ($userId === null) {
        // Return default avatar
        return '/images/default-avatar.png';
    }
    
    // Simplified user lookup
    $avatars = [
        1 => '/images/user1.jpg',
        2 => '/images/user2.jpg'
    ];
    
    // Return user's avatar or null if not found
    return $avatars[$userId] ?? null;
}

// Both these calls are valid
$avatar1 = getUserAvatar(1);      // Returns '/images/user1.jpg'
$avatar2 = getUserAvatar(null);   // Returns '/images/default-avatar.png'
$avatar3 = getUserAvatar(999);    // Returns null (user not found)

Union Types (PHP 8.0+)

Union types allow parameters or return values to be of multiple specified types.

function processIdentifier(string|int $id): array|bool {
    if (is_string($id)) {
        // Process string identifier
        return ['type' => 'string', 'value' => $id];
    } else if (is_int($id)) {
        // Process integer identifier
        return ['type' => 'integer', 'value' => $id];
    }
    
    // Something went wrong
    return false;
}

$result1 = processIdentifier("post_123");  // Returns array
$result2 = processIdentifier(456);         // Returns array

Working with Variable Numbers of Parameters

Sometimes you don't know how many parameters a function might receive. PHP offers multiple ways to handle this.

Using func_get_args() (Traditional Approach)

function sumAll() {
    $numbers = func_get_args();
    $total = 0;
    
    foreach ($numbers as $number) {
        $total += $number;
    }
    
    return $total;
}

echo sumAll(1, 2, 3);          // Output: 6
echo sumAll(10, 20, 30, 40);   // Output: 100

Using Variadic Parameters (PHP 5.6+)

The ellipsis (...) operator allows you to collect any number of arguments into an array.

function sumAll(...$numbers) {
    $total = 0;
    
    foreach ($numbers as $number) {
        $total += $number;
    }
    
    return $total;
}

echo sumAll(1, 2, 3);          // Output: 6
echo sumAll(10, 20, 30, 40);   // Output: 100

Combining Fixed and Variadic Parameters

function generateList($listType, ...$items) {
    $output = "<$listType>";
    
    foreach ($items as $item) {
        $output .= "<li>$item</li>";
    }
    
    $output .= "</$listType>";
    return $output;
}

// Ordered list with 3 items
echo generateList('ol', 'PHP', 'WordPress', 'MySQL');

// Unordered list with 4 items
echo generateList('ul', 'Themes', 'Plugins', 'Widgets', 'Customizer');

Practical WordPress Development Examples

Diagram

Custom Post Type Registration Function

/**
 * Register a custom post type for portfolio items
 *
 * @param string $slug The post type slug
 * @param string $singular_name Singular name for the post type
 * @param string $plural_name Plural name for the post type
 * @param array $features Array of features to support
 * @return WP_Post_Type|WP_Error The registered post type object or error
 */
function register_custom_portfolio($slug = 'portfolio', $singular_name = 'Portfolio Item', $plural_name = 'Portfolio Items', $features = ['title', 'editor', 'thumbnail']) {
    $labels = [
        'name' => $plural_name,
        'singular_name' => $singular_name,
        'add_new' => "Add New $singular_name",
        'add_new_item' => "Add New $singular_name",
        'edit_item' => "Edit $singular_name",
        'new_item' => "New $singular_name",
        'view_item' => "View $singular_name",
        'search_items' => "Search $plural_name",
        'not_found' => "No $plural_name found",
        'not_found_in_trash' => "No $plural_name found in trash"
    ];
    
    $args = [
        'labels' => $labels,
        'public' => true,
        'has_archive' => true,
        'menu_icon' => 'dashicons-portfolio',
        'supports' => $features,
        'rewrite' => ['slug' => $slug]
    ];
    
    return register_post_type($slug, $args);
}

// Register portfolio post type with default parameters
register_custom_portfolio();

// Register a "Projects" post type with custom features
register_custom_portfolio(
    'projects',
    'Project',
    'Projects',
    ['title', 'editor', 'thumbnail', 'excerpt', 'custom-fields']
);

Custom Theme Option Function

/**
 * Get a theme option with fallback default value
 *
 * @param string $option_name The option to retrieve
 * @param mixed $default_value Default value if option doesn't exist
 * @return mixed The option value or default value
 */
function get_theme_option(string $option_name, $default_value = '') {
    // Get all theme options from database
    $theme_options = get_option('my_theme_options', []);
    
    // Return the specific option or default value
    return isset($theme_options[$option_name]) ? $theme_options[$option_name] : $default_value;
}

// Usage examples
$primary_color = get_theme_option('primary_color', '#3498db');
$show_sidebar = get_theme_option('show_sidebar', true);
$footer_text = get_theme_option('footer_text', '© ' . date('Y') . ' My WordPress Site');

Practice Exercises

Exercise 1: Post Content Formatter

Create a function called formatContent that takes a string of content and formats it according to three parameters:

$content - The raw content string to format
$maxLength - Maximum number of words (default 50)
$addReadMore - Boolean to add "Read More" link (default true)

The function should trim the content to the specified length and add a "Read More" link if specified. Return the formatted content.

Exercise 2: User Role Checker

Create a function called userHasPermission that checks if a user has a specific permission based on their role. The function should:

Take parameters $userId and $requiredPermission
Return a boolean indicating whether the user has the permission
Use a predefined array of roles and their permissions

Exercise 3: Theme Color Generator

Create a function called generateColorPalette that generates a complete color palette based on a primary color. The function should:

Accept a parameter $primaryColor (a hex color code)
Return an array with additional colors (darker variant, lighter variant, complementary color)
Include proper type declarations for parameters and return value

Best Practices for Parameters and Return Values

Parameter Best Practices

Use Descriptive Parameter Names: Names should clearly indicate what the parameter is for
Provide Default Values for Optional Parameters: This makes your functions more flexible
Keep Required Parameters First: Place required parameters before optional ones
Don't Overload with Too Many Parameters: If a function needs many parameters, consider using an options array
Validate Input Parameters: Check that parameters are valid before using them
Use Type Declarations: When possible, specify parameter types to catch errors early

Return Value Best Practices

Return Early for Special Cases: Handle edge cases at the beginning of the function
Be Consistent with Return Types: A function should return the same type of value in all cases
Document Return Values: Use comments or docblocks to describe what your function returns
Return Values vs. Echo/Print: Functions should generally return values rather than outputting directly
Use Null or False for Errors: Return null, false, or WP_Error objects to indicate problems

Good Parameter Practices Example

/**
 * Generate navigation menu HTML
 *
 * @param string $menu_location Theme location for the menu
 * @param array $options Additional options for menu display
 * @return string|false Menu HTML or false on failure
 */
function generate_custom_menu(string $menu_location, array $options = []): string|false {
    // Set default options
    $defaults = [
        'container' => 'nav',
        'container_class' => 'site-navigation',
        'depth' => 2,
        'fallback_cb' => false
    ];
    
    // Merge user options with defaults
    $final_options = array_merge($defaults, $options);
    
    // Validate menu location
    if (!has_nav_menu($menu_location)) {
        return false;
    }
    
    // Start output buffering to capture menu HTML
    ob_start();
    
    // Generate the menu
    wp_nav_menu([
        'theme_location' => $menu_location,
        'container' => $final_options['container'],
        'container_class' => $final_options['container_class'],
        'depth' => $final_options['depth'],
        'fallback_cb' => $final_options['fallback_cb']
    ]);
    
    // Return the captured HTML
    return ob_get_clean();
}

Coming Up Next

In our next lecture, we'll explore default parameter values in more depth, and learn how they make our functions more flexible and robust.

Setting and using default parameter values
When and why to use default values
Common patterns for default values in WordPress
Best practices for default parameters

Course Progress

Learning Objectives

Making Functions Dynamic and Useful

Key Concepts

Function Parameters and Return Values: A Visual Model

Function Parameters in PHP

Basic Parameter Syntax

Simple Parameter Example

Multiple Parameters Example

Parameter Order Matters!

Working with Different Parameter Types

Working with Different Parameter Types

Type Declarations (Type Hinting)

Basic Type Declaration Syntax

Type Declaration Examples

WordPress Compatibility Note

Function Return Values

Basic Return Value Syntax

Simple Return Value Example

Return Type Declarations

Return Type Declaration Syntax

Return Type Examples

Return Type Enforcement

Real-World WordPress Examples

Custom Shortcode with Parameters

WordPress Template Function

Advanced Parameter Techniques

Named Arguments (PHP 8.0+)

Nullable Types (PHP 7.1+)

Union Types (PHP 8.0+)

Working with Variable Numbers of Parameters

Using func_get_args() (Traditional Approach)

Using Variadic Parameters (PHP 5.6+)

Combining Fixed and Variadic Parameters

Practical WordPress Development Examples

Custom Post Type Registration Function

Custom Theme Option Function

Practice Exercises

Exercise 1: Post Content Formatter

Exercise 2: User Role Checker

Exercise 3: Theme Color Generator

Best Practices for Parameters and Return Values

Parameter Best Practices

Return Value Best Practices

Good Parameter Practices Example

Further Reading

Coming Up Next