# jetbrains

**Repository Path**: edims/jetbrains

## Basic Information

- **Project Name**: jetbrains
- **Description**: php8 phpstorm注解帮助
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-01
- **Last Updated**: 2026-02-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# JetBrains PhpStorm 属性库

## 简介

这是一个 PHP 库，包含了 JetBrains PhpStorm IDE 所需的各类属性注解。这些属性是 PHP 8 引入的特性，用于向 PhpStorm 提供额外的类型信息和元数据，从而帮助 IDE 提供更准确的代码补全、类型检查和错误提示。

本库中的属性均定义在 `JetBrains\PhpStorm` 命名空间下，可直接在你的项目中使用。

## 功能特性

本库提供了丰富的属性注解，覆盖了以下场景：

- **类型定义**：通过 `ArrayShape` 定义数组的具体结构
- **废弃标记**：使用 `Deprecated` 标记已废弃的代码并提供替代建议
- **期望值约束**：`ExpectedValues` 用于限制参数或属性的可选值
- **不可变约束**：`Immutable` 用于标记不可变属性或类
- **纯函数标识**：`Pure` 用于标记无副作用的函数
- **特殊返回类型**：`NoReturn` 用于标识永远不会返回的函数
- **语言规范**：`Language` 用于指定特定语言版本的类型提示

## 环境要求

- PHP 8.0 或更高版本
- 支持 PHP 注解特性的 PHP 框架或 IDE

## 安装方式

通过 Composer 安装：

```bash
composer require jetbrains/phpstorm-attributes
```

## 核心属性说明

### ArrayShape

用于定义数组的具体结构，帮助 IDE 理解数组中每个元素的键名和类型。

```php
use JetBrains\PhpStorm\ArrayShape;

#[ArrayShape([
    'id' => 'int',
    'name' => 'string',
    'email' => 'string|null'
])]
function getUser(): array {
    // ...
}
```

### Deprecated

标记代码元素已废弃，可指定废弃原因、替代方案和建议使用的 PHP 版本。

```php
use JetBrains\PhpStorm\Deprecated;

#[Deprecated('Use newMethod() instead', 'newMethod', '8.0')]
function oldMethod(): void {
    // ...
}
```

### ExpectedValues

限制参数或属性的期望值集合，支持从类常量中获取值。

```php
use JetBrains\PhpStorm\ExpectedValues;

function configureOption(
    #[ExpectedValues(['debug', 'release'])]
    string $mode
): void {
    // ...
}
```

### Immutable

标记属性或类为不可变，确保其值在初始化后不会被修改。

```php
use JetBrains\PhpStorm\Immutable;

#[Immutable]
class Configuration {
    #[Immutable(Immutable::PRIVATE_WRITE_SCOPE)]
    public string $name;
}
```

### Pure

标识函数为纯函数，即没有副作用且返回值仅依赖于输入参数。

```php
use JetBrains\PhpStorm\Pure;

#[Pure]
function calculate(int $a, int $b): int {
    return $a + $b;
}
```

### NoReturn

用于标记永远不会返回的函数（如抛出异常或调用 `exit()` 的函数）。

```php
use JetBrains\PhpStorm\NoReturn;

#[NoReturn]
function terminate(): void {
    // 记录日志
    exit(1);
}
```

## 内部属性

以下属性主要供 PhpStorm 内部使用，普通开发者一般不需要直接使用：

- `LanguageLevelTypeAware`：根据 PHP 语言级别提供类型感知
- `PhpStormStubsElementAvailable`：标记特定 PHP 版本可用的存根元素
- `ReturnTypeContract`：为条件返回类型提供约束说明

## 版本兼容性

本库中的 `Deprecated` 属性支持以下 PHP 版本的标记：

- 5.3 - 5.6
- 7.0 - 7.4
- 8.0

## 贡献指南

欢迎社区贡献！请确保：

1. 遵循 PSR 代码规范
2. 添加适当的单元测试
3. 更新相关文档
4. 提交清晰的 commit 信息

## 许可证

本项目采用 [MIT 许可证](LICENSE)。

## 相关资源

- [PhpStorm 官方文档](https://www.jetbrains.com/phpstorm/)
- [PHP 注解文档](https://www.php.net/manual/en/language.attributes.php)
- [项目 Issues](https://gitee.com/edims/jetbrains/issues)