跳到主要内容

核心功能的弃用

弃用是一种鼓励用户放弃某些功能或实践，而选择其他替代方案的方法，这种方法既不破坏向后兼容性，也不完全禁止其使用。 引用维基百科关于弃用的文章：

尽管已弃用的软件功能仍然存在于软件中，但其使用可能会引发警告消息，建议采用替代方案；弃用状态也可能表明该功能将在未来被移除。 为了提供向后兼容性，并为程序员提供时间来使受影响的代码符合新的标准，因此会先弃用功能，而不是立即删除。

有各种原因可能导致某个函数、方法或功能被弃用。 举例来说：

  • 我们可能希望移除不再使用的函数。
  • 我们可能决定更改或改进某个函数的工作方式，但由于会破坏向后兼容性，因此我们需要弃用旧的函数。
  • 我们可能希望标准化命名约定。
  • 我们可能会发现可以合并相似功能的机会，以避免在不同的地方重复使用相同的代码。

虽然弃用通知不太理想或美观，但它们仅仅是_警告_，而不是_错误_。

商店所有者： 弃用警告并不意味着您的商店已损坏，它只是提醒您需要更新代码。

我们如何弃用函数？​

当我们在 WooCommerce 中弃用某些内容时，我们会采取一些措施，以便清楚地告知开发者，并保持向后兼容性。

  1. 我们会在函数或方法中添加文档块，说明该函数在哪个版本中被弃用，例如：@deprecated 2.x.x。
  2. 我们会使用我们自己的 wc_deprecated_function 函数添加警告通知，该通知显示了哪个版本、哪个函数以及可用的替代方案。 稍后会详细介绍。
  3. 我们会移除整个代码库中对已弃用函数的引用。

该函数或方法本身不会从代码库中删除。 这样可以保持向后兼容性，直到被移除——通常是在一年或几个主要版本之后。

我们上面提到了 wc_deprecated_function，这是一个我们自己的 _deprecated_function WordPress 函数的包装器。 它的工作方式非常相似，只是它会强制记录条目，而不是显示它——无论在 AJAX 事件期间 WP_DEBUG 的值是多少——这样可以防止 AJAX 请求因该通知而中断。

当调用已弃用的函数时会发生什么？​

如果某个扩展或主题使用了已弃用的函数，您可能会看到如下所示的警告：

Notice: woocommerce_show_messages 已在版本 2.1 中被弃用！请使用 wc_print_notices 代替。位于 /srv/www/wordpress-default/wp-includes/functions.php 第 3783 行

这会告诉您哪个函数已被弃用，自何时起，位于何处，以及有哪些可用的替代方案。

通常，Notice 和 Warning 会在页面上显示，但有一些插件可以帮助您收集并将它们以美观的方式显示在网站的页脚中。例如，您可以考虑使用 Query Monitor。

生产环境中的警告（店主 - 请阅读！）​

强烈建议不要在您的生产环境中显示 PHP Notice 和 Warning（或者任何 Error）。 它们可能会泄露有关您配置的信息，而恶意用户可能会利用这些信息来访问您的商店。 确保它们对公众隐藏，并可以选择将其记录下来。

在 WordPress 中，您可以通过在 wp-config.php 文件中添加或修改一些常量来实现这一点：

define( 'WP_DEBUG', false );

在某些主机上，由于主机的配置，Error 可能仍然可见。 为了强制它们不显示，您可能需要在 wp-config.php 文件中添加以下内容：

@ini_set( 'display_errors', 0 );

要记录 Notice 而不是显示它们，请使用以下代码：

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

WordPress 错误日志的默认位置是 wp-content/debug.log。

请注意，此日志可能对公众可见，这可能会带来安全风险。 为了使其保持私有，您可以使用插件或在 wp-config.php 文件中定义自定义路径。

<?php
/**
 * 插件名称: 自定义调试日志路径
 */

ini_set( 'error_log', '/path/to/site/logs/debug.log' );