dede common.func.php文件有何作用？

Of course. Let's dive deep into dede/common.func.php.

This is one of the most important and powerful files in the DedeCMS (织梦CMS) system, especially for developers and template designers who want to go beyond the basic template tags.

What is dede/common.func.php?

In simple terms, common.func.php is the central "helper" or "utility" file for DedeCMS. It's a collection of custom PHP functions that are not part of the core DedeCMS codebase but are essential for extending its functionality.

Its primary purposes are:

1. Code Reusability: It stores functions that are used in multiple places across the site (both in PHP files and templates), preventing code duplication.
2. Custom Functionality: Developers can add their own PHP functions to this file and then call them directly from any template file using the {dede:global name='funcname' function='myCustomFunction' /} or {dede:myfunction} syntax.
3. Template Enhancement: It provides a way to perform complex logic or data manipulation within templates, which would otherwise require modifying core PHP files.

Key Characteristics

• Global Scope: Functions defined in this file are automatically "available" to the entire DedeCMS application without needing to manually include or require the file.
• Template-Friendly: Many functions are specifically designed to be called from Dede's template engine (DedeTag).
• Community-Driven: A significant portion of the functions in this file, especially in older versions, were contributed by the DedeCMS user community to solve common problems.

Commonly Used Functions (with Examples)

Here are some of the most frequently used functions you'll find in common.func.php, along with explanations and examples of how to use them.

GetDateTimeMk($datetime)

• Purpose: Converts a standard datetime string (e.g., from the database) into a Unix timestamp. This is useful for date calculations.
• Usage in Template:

  {dede:field name='pubdate' function='GetDateTimeMk(@me)'/}

• Explanation: This takes the pubdate of an article and converts it into a numeric timestamp, which can then be used with other date functions.

MyDate($format, $timestamp)

• Purpose: The opposite of GetDateTimeMk. It formats a Unix timestamp into a human-readable date string. It's a more flexible version of PHP's date() function.
• Usage in Template:

  {dede:field name='pubdate' function='MyDate("Y-m-d H:i:s", @me)'/}

  This is actually the default behavior, so you could just use {dede:field.pubdate/}, but the function is useful for custom formatting.

• Explanation: @me in DedeTag represents the current value of the field being processed. So, it takes the article's publication timestamp and formats it as "Year-Month-Day Hour:Minute:Second".

cn_substr($str, $length, $dot = '...')

• Purpose: A very popular function for cutting off text (substring) while correctly handling multi-byte Chinese characters (using gbk or utf-8 encoding). This prevents garbled text when cutting a string in the middle of a Chinese character.
• Usage in Template (to show an article摘要 with a 100-character limit):

  {dede:field name='description' function='cn_substr(@me, 100)'/}

• Explanation: This safely cuts the article's description to a maximum of 100 characters. If the original text is longer, it adds by default.

GetTags($aid)

• Purpose: Retrieves all the tags associated with a specific article ID and returns them as a comma-separated string.
• Usage in Template (inside an article list or single article page):

  {dede:field name='id' function='GetTags(@me)'/}

• Explanation: This gets the ID of the current article ({dede:field.id/}) and passes it to the GetTags function, which then fetches and returns all its tags, like "dedecms,php,教程".

GetOneArchive($typeid)

• Purpose: To get the URL of the archive list page for a specific category ID.
• Usage in Template:

  {dede:field name='typeid' function='GetOneArchive(@me)'/}

• Explanation: This is useful for creating dynamic links. If you are on an article page and want to link back to its category's archive page, you can use this function with the article's typeid.

GetImage($img, $style = '')

• Purpose: To get the full path of an image, often applying a specified image style (like watermarks or resizing).
• Usage in Template:

  <img src="{dede:field name='litpic' function='GetImage(@me)'}" alt="{dede:field.title/}" />

• Explanation: It takes the relative path of a thumbnail (litpic) and converts it into a full, absolute URL, ensuring the image can be displayed correctly from any location.

How to Add Your Own Custom Function

This is where the real power of common.func.php shines. Let's say you want to create a function that converts a number into a "readable" format (e.g., 1500 -> 1.5k).

Step 1: Add the function to dede/common.func.php

Open the file and add your PHP function at the end.

// File: dede/common.func.php
// ... (other existing functions) ...
/**
 * Converts a number to a short, readable format (e.g., 1500 -> 1.5k)
 *
 * @param int $num The number to format.
 * @return string The formatted number string.
 */
function number_format_short($num) {
    if ($num > 1000) {
        $x = round($num);
        $x_number_format = number_format($x);
        $x_array = explode(',', $x_number_format);
        $x_parts = array('k', 'm', 'b', 't');
        $x_display = round($x / 1000, 2);
        return $x_display . 'k';
    }
    return $num;
}

Step 2: Use the function in your template

Now, you can call this function from any Dede template.

{dede:field name='click' function='number_format_short(@me)'/}

If the click (view count) field for an article is 1500, the template will display 5k.

Best Practices and Important Notes

1. Backup Before Editing: Always create a backup of common.func.php before you make any changes. A small syntax error can break your entire website.
2. Don't Edit Core Files: While common.func.php is a "custom" file, it's still part of the DedeCMS file structure. When you upgrade DedeCMS, you will need to carefully merge your changes with the new version of the file or your changes will be lost.
3. Use Meaningful Names: When adding your own functions, use descriptive names (like number_format_short) to avoid conflicts with future DedeCMS updates or other functions.
4. Security: Be careful when using user-supplied data (@me) in your custom functions. Ensure you are sanitizing input to prevent security vulnerabilities like SQL injection or XSS attacks, although this is less of a concern when the output is just text.

Summary

In conclusion, dede/common.func.php is an indispensable tool for any DedeCMS developer. Mastering its use is key to building a more powerful, flexible, and maintainable website on the DedeCMS platform.