From 95001d30965d1057e2b115691a98a4047d372b79 Mon Sep 17 00:00:00 2001 From: catch Date: Fri, 13 Apr 2012 17:01:13 +0900 Subject: [PATCH] Issue #1480866 by hansyg, underq, Berdir, tstoeckler, cosmicdreams: Add type-hinting and parameter type documentation for comment objects. --- core/modules/comment/comment.admin.inc | 4 +- core/modules/comment/comment.api.php | 36 ++++++++-------- core/modules/comment/comment.module | 57 +++++++++++++++----------- core/modules/comment/comment.pages.inc | 9 ++-- core/modules/comment/comment.test | 10 ++--- 5 files changed, 60 insertions(+), 56 deletions(-) diff --git a/core/modules/comment/comment.admin.inc b/core/modules/comment/comment.admin.inc index c0f92d98cee..d84b785c278 100644 --- a/core/modules/comment/comment.admin.inc +++ b/core/modules/comment/comment.admin.inc @@ -264,7 +264,7 @@ function comment_confirm_delete_page($cid) { /** * Form constructor for the confirmation form for comment deletion. * - * @param $comment + * @param Comment $comment * The comment that is about to be deleted. * * @ingroup forms @@ -272,7 +272,7 @@ function comment_confirm_delete_page($cid) { * @see comment_confirm_delete_submit() * @see confirm_form() */ -function comment_confirm_delete($form, &$form_state, $comment) { +function comment_confirm_delete($form, &$form_state, Comment $comment) { $form['#comment'] = $comment; // Always provide entity id in the same form key as in the entity edit form. $form['cid'] = array('#type' => 'value', '#value' => $comment->cid); diff --git a/core/modules/comment/comment.api.php b/core/modules/comment/comment.api.php index f270aadade1..eb9f34d4acf 100644 --- a/core/modules/comment/comment.api.php +++ b/core/modules/comment/comment.api.php @@ -16,10 +16,10 @@ * This hook is invoked from comment_save() before the comment is saved to the * database. * - * @param $comment + * @param Comment $comment * The comment object. */ -function hook_comment_presave($comment) { +function hook_comment_presave(Comment $comment) { // Remove leading & trailing spaces from the comment subject. $comment->subject = trim($comment->subject); } @@ -27,10 +27,10 @@ function hook_comment_presave($comment) { /** * Respond to creation of a new comment. * - * @param $comment + * @param Comment $comment * The comment object. */ -function hook_comment_insert($comment) { +function hook_comment_insert(Comment $comment) { // Reindex the node when comments are added. search_touch_node($comment->nid); } @@ -38,10 +38,10 @@ function hook_comment_insert($comment) { /** * Respond to updates to a comment. * - * @param $comment + * @param Comment $comment * The comment object. */ -function hook_comment_update($comment) { +function hook_comment_update(Comment $comment) { // Reindex the node when comments are updated. search_touch_node($comment->nid); } @@ -49,10 +49,10 @@ function hook_comment_update($comment) { /** * Act on comments being loaded from the database. * - * @param $comments + * @param array $comments * An array of comment objects indexed by cid. */ -function hook_comment_load($comments) { +function hook_comment_load(Comment $comments) { $result = db_query('SELECT cid, foo FROM {mytable} WHERE cid IN (:cids)', array(':cids' => array_keys($comments))); foreach ($result as $record) { $comments[$record->cid]->foo = $record->foo; @@ -62,7 +62,7 @@ function hook_comment_load($comments) { /** * Act on a comment that is being assembled before rendering. * - * @param $comment + * @param Comment $comment * Passes in the comment the action is being performed on. * @param $view_mode * View mode, e.g. 'full', 'teaser'... @@ -71,7 +71,7 @@ function hook_comment_load($comments) { * * @see hook_entity_view() */ -function hook_comment_view($comment, $view_mode, $langcode) { +function hook_comment_view(Comment $comment, $view_mode, $langcode) { // how old is the comment $comment->time_ago = time() - $comment->changed; } @@ -108,20 +108,20 @@ function hook_comment_view_alter(&$build) { /** * Respond to a comment being published by a moderator. * - * @param $comment + * @param Comment $comment * The comment the action is being performed on. */ -function hook_comment_publish($comment) { +function hook_comment_publish(Comment $comment) { drupal_set_message(t('Comment: @subject has been published', array('@subject' => $comment->subject))); } /** * Respond to a comment being unpublished by a moderator. * - * @param $comment + * @param Comment $comment * The comment the action is being performed on. */ -function hook_comment_unpublish($comment) { +function hook_comment_unpublish(Comment $comment) { drupal_set_message(t('Comment: @subject has been unpublished', array('@subject' => $comment->subject))); } @@ -132,14 +132,14 @@ function hook_comment_unpublish($comment) { * field_attach_delete() is called and before the comment is actually removed * from the database. * - * @param $comment + * @param Comment $comment * The comment object for the comment that is about to be deleted. * * @see hook_comment_delete() * @see comment_delete_multiple() * @see entity_delete_multiple() */ -function hook_comment_predelete($comment) { +function hook_comment_predelete(Comment $comment) { // Delete a record associated with the comment in a custom table. db_delete('example_comment_table') ->condition('cid', $comment->cid) @@ -153,14 +153,14 @@ function hook_comment_predelete($comment) { * field_attach_delete() has called and after the comment has been removed from * the database. * - * @param $comment + * @param Comment $comment * The comment object for the comment that has been deleted. * * @see hook_comment_predelete() * @see comment_delete_multiple() * @see entity_delete_multiple() */ -function hook_comment_delete($comment) { +function hook_comment_delete(Comment $comment) { drupal_set_message(t('Comment: @subject has been deleted', array('@subject' => $comment->subject))); } diff --git a/core/modules/comment/comment.module b/core/modules/comment/comment.module index 1a3580ff433..a7144195f41 100644 --- a/core/modules/comment/comment.module +++ b/core/modules/comment/comment.module @@ -164,7 +164,7 @@ function comment_node_type_load($name) { /** * Entity uri callback. */ -function comment_uri($comment) { +function comment_uri(Comment $comment) { return array( 'path' => 'comment/' . $comment->cid, 'options' => array('fragment' => 'comment-' . $comment->cid), @@ -934,7 +934,7 @@ function comment_prepare_thread(&$comments) { /** * Generates an array for rendering a comment. * - * @param $comment + * @param Comment $comment * The comment object. * @param $node * The node the comment is attached to. @@ -947,7 +947,7 @@ function comment_prepare_thread(&$comments) { * @return * An array as expected by drupal_render(). */ -function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) { +function comment_view(Comment $comment, $node, $view_mode = 'full', $langcode = NULL) { if (!isset($langcode)) { $langcode = $GLOBALS['language_content']->langcode; } @@ -1004,7 +1004,7 @@ function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) { * The content built for the comment (field values, comments, file attachments * or other comment components) will vary depending on the $view_mode parameter. * - * @param $comment + * @param Comment $comment * A comment object. * @param $node * The node the comment is attached to. @@ -1014,7 +1014,7 @@ function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) { * (optional) A language code to use for rendering. Defaults to the global * content language of the current request. */ -function comment_build_content($comment, $node, $view_mode = 'full', $langcode = NULL) { +function comment_build_content(Comment $comment, $node, $view_mode = 'full', $langcode = NULL) { if (!isset($langcode)) { $langcode = $GLOBALS['language_content']->langcode; } @@ -1048,7 +1048,7 @@ function comment_build_content($comment, $node, $view_mode = 'full', $langcode = /** * Adds reply, edit, delete, etc. links, depending on user permissions. * - * @param $comment + * @param Comment $comment * The comment object. * @param $node * The node the comment is attached to. @@ -1056,7 +1056,7 @@ function comment_build_content($comment, $node, $view_mode = 'full', $langcode = * @return * A structured array of links. */ -function comment_links($comment, $node) { +function comment_links(Comment $comment, $node) { $links = array(); if ($node->comment == COMMENT_NODE_OPEN) { if (user_access('administer comments') && user_access('post comments')) { @@ -1450,13 +1450,13 @@ function comment_user_predelete($account) { * @param $op * The operation that is to be performed on the comment. Only 'edit' is * recognized now. - * @param $comment + * @param Comment $comment * The comment object. * * @return * TRUE if the current user has acces to the comment, FALSE otherwise. */ -function comment_access($op, $comment) { +function comment_access($op, Comment $comment) { global $user; if ($op == 'edit') { @@ -1467,10 +1467,10 @@ function comment_access($op, $comment) { /** * Accepts a submission of new or changed comment content. * - * @param $comment + * @param Comment $comment * A comment object. */ -function comment_save($comment) { +function comment_save(Comment $comment) { $comment->save(); } @@ -1643,12 +1643,12 @@ function comment_get_display_page($cid, $node_type) { /** * Page callback: Displays the comment editing form. * - * @param $comment + * @param Comment $comment * The comment object representing the comment to be edited. * * @see comment_menu() */ -function comment_edit_page($comment) { +function comment_edit_page(Comment $comment) { drupal_set_title(t('Edit comment %comment', array('%comment' => $comment->subject)), PASS_THROUGH); $node = node_load($comment->nid); return drupal_get_form("comment_node_{$node->type}_form", $comment); @@ -1673,7 +1673,7 @@ function comment_forms() { * @see comment_form_build_preview() * @ingroup forms */ -function comment_form($form, &$form_state, $comment) { +function comment_form($form, &$form_state, Comment $comment) { global $user, $language_content; // During initial form build, add the comment entity to the form state for @@ -1887,9 +1887,11 @@ function comment_form_build_preview($form, &$form_state) { /** * Generates a comment preview. * + * @param Comment $comment + * * @see comment_form_build_preview() */ -function comment_preview($comment) { +function comment_preview(Comment $comment) { global $user; drupal_set_title(t('Preview comment'), PASS_THROUGH); @@ -1986,8 +1988,11 @@ function comment_form_validate($form, &$form_state) { /** * Prepare a comment for submission. + * + * @param Comment $comment + * */ -function comment_submit($comment) { +function comment_submit(Comment $comment) { if (empty($comment->date)) { $comment->date = 'now'; } @@ -2327,15 +2332,15 @@ function comment_action_info() { /** * Publishes a comment. * - * @param $comment - * An optional comment object. + * @param Comment $comment + * (optional) A comment object to publish. * @param array $context * Array with components: * - 'cid': Comment ID. Required if $comment is not given. * * @ingroup actions */ -function comment_publish_action($comment, $context = array()) { +function comment_publish_action(Comment $comment = NULL, $context = array()) { if (isset($comment->subject)) { $subject = $comment->subject; $comment->status = COMMENT_PUBLISHED; @@ -2354,15 +2359,15 @@ function comment_publish_action($comment, $context = array()) { /** * Unpublishes a comment. * - * @param $comment - * An optional comment object. + * @param Comment|null $comment + * (optional) A comment object to unpublish. * @param array $context * Array with components: * - 'cid': Comment ID. Required if $comment is not given. * * @ingroup actions */ -function comment_unpublish_action($comment, $context = array()) { +function comment_unpublish_action(Comment $comment = NULL, $context = array()) { if (isset($comment->subject)) { $subject = $comment->subject; $comment->status = COMMENT_NOT_PUBLISHED; @@ -2381,7 +2386,7 @@ function comment_unpublish_action($comment, $context = array()) { /** * Unpublishes a comment if it contains certain keywords. * - * @param $comment + * @param Comment $comment * Comment object to modify. * @param array $context * Array with components: @@ -2392,7 +2397,7 @@ function comment_unpublish_action($comment, $context = array()) { * @see comment_unpublish_by_keyword_action_form() * @see comment_unpublish_by_keyword_action_submit() */ -function comment_unpublish_by_keyword_action($comment, $context) { +function comment_unpublish_by_keyword_action(Comment $comment, $context) { foreach ($context['keywords'] as $keyword) { $text = drupal_render($comment); if (strpos($text, $keyword) !== FALSE) { @@ -2433,9 +2438,11 @@ function comment_unpublish_by_keyword_action_submit($form, $form_state) { /** * Saves a comment. * + * @param Comment $comment + * * @ingroup actions */ -function comment_save_action($comment) { +function comment_save_action(Comment $comment) { comment_save($comment); cache_clear_all(); watchdog('action', 'Saved comment %title', array('%title' => $comment->subject)); diff --git a/core/modules/comment/comment.pages.inc b/core/modules/comment/comment.pages.inc index 344e75717b7..21fe465e5da 100644 --- a/core/modules/comment/comment.pages.inc +++ b/core/modules/comment/comment.pages.inc @@ -47,12 +47,9 @@ function comment_reply($node, $pid = NULL) { // $pid indicates that this is a reply to a comment. if ($pid) { if (user_access('access comments')) { - // Load the comment whose cid = $pid - $comment = db_query('SELECT c.*, u.uid, u.name AS registered_name, u.signature, u.signature_format, u.picture, u.data FROM {comment} c INNER JOIN {users} u ON c.uid = u.uid WHERE c.cid = :cid AND c.status = :status', array( - ':cid' => $pid, - ':status' => COMMENT_PUBLISHED, - ))->fetchObject(); - if ($comment) { + // Load the parent comment. + $comment = comment_load($pid); + if ($comment->status = COMMENT_PUBLISHED) { // If that comment exists, make sure that the current comment and the // parent comment both belong to the same parent node. if ($comment->nid != $node->nid) { diff --git a/core/modules/comment/comment.test b/core/modules/comment/comment.test index 925751398ed..259e420c979 100644 --- a/core/modules/comment/comment.test +++ b/core/modules/comment/comment.test @@ -96,7 +96,7 @@ class CommentHelperCase extends DrupalWebTestCase { /** * Checks current page for specified comment. * - * @param object $comment + * @param Comment $comment * The comment object. * @param boolean $reply * Boolean indicating whether the comment is a reply to another comment. @@ -104,8 +104,8 @@ class CommentHelperCase extends DrupalWebTestCase { * @return boolean * Boolean indicating whether the comment was found. */ - function commentExists($comment, $reply = FALSE) { - if ($comment && is_object($comment)) { + function commentExists(Comment $comment = NULL, $reply = FALSE) { + if ($comment) { $regex = '/' . ($reply ? '
(.*?)' : ''); $regex .= 'drupalPost('comment/' . $comment->id . '/delete', array(), t('Delete')); $this->assertText(t('The comment and all its replies have been deleted.'), t('Comment deleted.')); }