# Adding custom permissions for WordPress roles

> Give WordPress user roles extra capabilities, or create custom permissions, by adding code to your theme's functions.php file.

Source: https://helpcenter.ruachost.com/wordpress/guides/adding-custom-permissions-for-wordpress-roles/

WordPress uses **roles and capabilities** to control what users can and cannot do on a site. By default, WordPress provides six predefined roles: **Super Admin, Administrator, Editor, Author, Contributor, and Subscriber**. Each role has its own set of permissions. On **ruachost.com**, you can extend these roles by adding **custom permissions** with PHP.

## Why Add Custom Permissions?

- Fine‑tune user access to specific tasks.
- Allow contributors to edit pages but not posts.
- Restrict plugin or theme management to certain roles.
- Improve site security by limiting unnecessary privileges.

## Steps to Add Custom Permissions

1. **Log in to WordPress** with an administrator account.
2. In the dashboard, go to **Appearance → Theme Editor**.
3. Select your active theme and open the **functions.php** file.
4. Add the following code snippet:

   ```
   // Add a custom role with specific permissions
   $result = add_role(
       'new', __( 'New' ),
       array(
           'read' => true,            // allow reading
           'edit_posts' => false,     // disallow editing own posts
           'edit_pages' => true,      // allow editing pages
           'edit_others_posts' => false, // disallow editing others' posts
           'create_posts' => false    // disallow creating new posts
       )
   );
   ```

   - Replace `'new'` with your custom role slug.
   - Adjust `true` or `false` values to enable/disable specific capabilities.
5. Save the file.
6. Log out and back in → The new role will now appear under **Users → Add New**.

## Important Notes

- Always back up your theme before editing `functions.php`.
- Use a **child theme** to preserve changes during updates.
- Some capabilities (like `unfiltered_upload`) are disabled by default and must be explicitly enabled in `wp-config.php`.