Consider this code in akismet.php from the ubiquitous Akismet plugin for WordPress:
define('AKISMET_PLUGIN_URL', plugin_dir_url( __FILE__ ));
My WordPress installation is at /usr/share/wordpress, but the Akismet plugin is installed to /var/lib/wordpress/plugins/akismet/ and there is a symlink (symbolic link) inbetween. This means that __FILE__ is /var/lib/wordpress/plugins/akismet/akismet.php but plugin_dir_url does not understand this, and will incorrectly return:
/wp-content/plugins/var/lib/wordpress/plugins/akismet/
This is not a proper URL for my WordPress installation!
I’m still on WordPress 3.0.something, but it seems like this issue is still a problem in newer versions. There are a number of bug reports for this and similar issues:
I used the WP_fix_for_plugin_basename_to_allow_symlinks_2011-07-28* pair of patches attached to bug report 16953 to solve the issue on my server. It will patch the plugin_basename implementation, which seems to contain the root cause of this issue.